@mrciphersmith/keryx 0.3.1 → 0.3.3

package/src/gdskills/bundled/stacks/php-laravel/governance/scout.json

@@ -0,0 +1,33 @@
+[
+  {
+    "query": "Use when implementing or extending a feature in a PHP 8.2+ / Laravel application -- controllers, Form Request validation, Eloquent models and relationships, migrations, route-model binding, middleware, queued jobs, and service container bindings.",
+    "decision": "fork",
+    "topMatch": "php-laravel/php-laravel-testing",
+    "recordedAt": "2026-09-25T15:27:29.539Z",
+    "skillName": "php-laravel-implementation",
+    "justification": "Nearest match php-laravel/php-laravel-testing (0.47) is this pack's own testing skill -- writes Pest/PHPUnit tests, never touches production controllers/models/migrations. ruby-rails-implementation (0.26) and nodejs-implementation (0.24) implement features for a different language/framework entirely (Ruby/Rails, Node/Express), sharing only generic implementation vocabulary, not Laravel's Eloquent/Form-Request/service-container API surface. No existing skill covers implementing a PHP/Laravel feature, so this is a genuine create."
+  },
+  {
+    "query": "Use when a Laravel application's test suite needs writing, extending, or fixing -- Pest or PHPUnit feature/unit tests, model factories, RefreshDatabase, HTTP testing helpers, and Queue/Mail/Event/Http fakes.",
+    "decision": "fork",
+    "topMatch": "ruby-rails/ruby-rails-testing",
+    "recordedAt": "2026-09-25T15:27:40.315Z",
+    "skillName": "php-laravel-testing",
+    "justification": "Nearest match ruby-rails-testing (0.35) covers RSpec/Minitest for a different language/framework (Ruby/Rails), not Pest/PHPUnit or Laravel's Queue/Mail/Event/Http fakes. go-testing (0.24) and react-testing (0.24) are for unrelated stacks (Go's testing package, Jest/RTL). No existing skill covers Laravel's own test tooling (Pest, factories, RefreshDatabase, framework fakes), so this is a genuine create."
+  },
+  {
+    "query": "Use when composer install/update fails, PHP fatal errors block a Laravel app from booting, phpstan/larastan reports a failing analysis, or a previously-passing test suite is now failing -- resolves dependency conflicts, autoload issues, config/service-provider errors, and static-analysis findings with the smallest root-cause fix.",
+    "decision": "fork",
+    "topMatch": "ruby-rails/ruby-rails-build-fix",
+    "recordedAt": "2026-09-25T15:28:05.422Z",
+    "skillName": "php-laravel-build-fix",
+    "justification": "Nearest match ruby-rails-build-fix (0.39) resolves Bundler/Gemfile conflicts and Rails boot errors -- not composer.json/composer.lock conflicts, PSR-4 autoload mismatches, or phpstan/Larastan findings, none of which apply to a Ruby/Bundler toolchain. python-build-fix (0.25) and nodejs-build-fix (0.21) resolve pip/npm/tsc failures for unrelated languages. No existing skill knows Composer's dependency resolution, PSR-4 autoloading, or PHP static-analysis tooling, so this is a genuine create."
+  },
+  {
+    "query": "Use when auditing a PHP/Laravel diff before merge for Eloquent and Blade pitfalls -- $fillable/$guarded mass-assignment gaps, missing eager-loaded relationships causing N+1 queries, string-interpolated DB::raw() SQL, unescaped {!! !!} Blade output, a route dropped from VerifyCsrfToken coverage, and a queued job with no idempotency guard. Read-only, no edits.",
+    "decision": "create",
+    "topMatch": "ruby-rails/ruby-rails-code-review",
+    "recordedAt": "2026-09-25T17:49:43.838Z",
+    "skillName": "php-laravel-code-review"
+  }
+]

package/src/gdskills/bundled/stacks/php-laravel/pack.json

@@ -0,0 +1,41 @@
+{
+  "id": "php-laravel",
+  "family": "framework",
+  "modules": ["php-laravel-rules", "php-laravel-skills"],
+  "detectionMarkers": ["php", "laravel"],
+  "provenance": {
+    "origin": "authored",
+    "sourceRef": "flow 337, Wave 4 batch 5"
+  },
+  "stability": "experimental",
+  "skills": {
+    "implement": ["php-laravel-implementation"],
+    "test": ["php-laravel-testing"],
+    "review": ["php-laravel-code-review"],
+    "build-fix": ["php-laravel-build-fix"],
+    "migrate": []
+  },
+  "agentProfile": {
+    "displayName": "PHP / Laravel",
+    "auditFocus": [
+      "an Eloquent create/update fed straight from $request->all() instead of validated() or an explicit $fillable/$guarded allowlist -- mass-assignment risk",
+      "raw SQL string interpolation (DB::select/DB::statement with concatenated values) instead of parameter bindings or the query builder/Eloquent",
+      "a relationship accessed inside a loop with no eager load (with()/load()) on the collection it iterates -- N+1 queries",
+      "Blade {!! !!} unescaped output rendering a value that traces back to user input",
+      "a state-changing route (POST/PUT/PATCH/DELETE) missing CSRF protection or excluded from the VerifyCsrfToken middleware without a stated reason",
+      "a queue job with no idempotency handling (unique(), a dedupe key, or a check before side-effecting work) on a connection that can redeliver or retry it -- true of most production queue configurations"
+    ],
+    "buildCommands": [
+      "composer install",
+      "php artisan config:clear (when config/env-dependent errors appear)",
+      "./vendor/bin/phpstan analyse (when the project has a phpstan/larastan config)",
+      "php artisan test (or ./vendor/bin/pest / ./vendor/bin/phpunit)"
+    ],
+    "fixGuardrails": [
+      "Never silence a static-analysis finding with a blanket @phpstan-ignore or @psalm-suppress instead of fixing the root cause.",
+      "Never widen $fillable to a blanket guard-nothing allowlist, or swap $guarded to [] to make a mass-assignment error disappear.",
+      "Never disable CSRF verification for a route or add it to VerifyCsrfToken's except list just to make a failing request succeed.",
+      "Never delete or skip a failing test to reach a green build."
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/php-laravel/rules/coding-style.mdc

@@ -0,0 +1,82 @@
+---
+extends: common
+paths: ["**/*.php"]
+metadata:
+  origin: authored
+---
+
+# PHP / Laravel coding style
+
+Narrows `core-common-rules`' stack-agnostic style rules to modern PHP
+(8.2+) and Laravel (11/12/13) idiom. Applies only to `*.php` files —
+everything not PHP/Laravel-specific still comes from the common rules
+this file `extends`.
+
+## Naming and structure
+
+- Classes, interfaces, enums, and traits are `StudlyCase`; methods and
+  properties are `camelCase`; constants and enum cases are
+  `SCREAMING_SNAKE_CASE` unless the enum case is meant to read as a label.
+- Follow Laravel's default directory conventions
+  (`app/Models`, `app/Http/Controllers`, `app/Http/Requests`,
+  `app/Providers`, `app/Jobs`, `database/migrations`) rather than
+  inventing a parallel structure for the same kind of class.
+- A controller method stays thin: validate (via a Form Request), delegate
+  to a model/action/service, return a response — push business rules into
+  a model method, an action class, or a service, not the controller.
+- Type-hint every parameter, property, and return value that can be
+  typed; PHP 8.2+ intersection types and `never`/`static` return types are
+  fair game where they genuinely describe the contract.
+
+## PHP 8.2+ language features
+
+- `readonly` properties for value objects and anything constructed once
+  and never mutated (a DTO, an immutable config value) instead of a
+  mutable property guarded only by convention.
+- Native `enum` (backed by `string`/`int` when the value needs to persist
+  to a column or API payload) instead of class constants for a fixed set
+  of related values.
+- First-class callable syntax (`$this->method(...)`, `Str::slug(...)`)
+  instead of a string/array callable (`[$this, 'method']`) or an
+  unnecessary closure wrapper when passing a method as a callback.
+- Constructor property promotion (`public function __construct(private
+  readonly OrderRepository $orders) {}`) for simple DTOs and services
+  instead of repeating each property as a separate declaration plus
+  assignment.
+
+## Eloquent models
+
+- Declare `protected $fillable` (an explicit allowlist) or `protected
+  $guarded` on every model that is ever mass-assigned; do not leave a
+  model without either and rely on `Model::unguard()` outside of a
+  seeder/test context.
+- Cast attributes with the model's `casts()` method (or the `$casts`
+  property on codebases not yet migrated to it) rather than hand-parsing
+  dates/JSON/enums in accessors.
+- Put a relationship's return type on the method
+  (`: HasMany`, `: BelongsTo`, ...) so IDEs and static analysis can follow
+  it.
+
+## Controllers, routes, and requests
+
+- Route parameters use route-model binding
+  (`Route::get('/users/{user}', ...)` resolving to a typed `User $user`
+  parameter) instead of manually calling `User::findOrFail($id)` in every
+  controller method that already receives the bound model.
+- Validate every request that accepts user input through a Form Request
+  class (`php artisan make:request`) or `$request->validate([...])`, not
+  by reading raw `$request->all()`/`$request->input()` values straight
+  into model or database calls.
+- Register route-specific middleware with `->middleware(...)` on the
+  route/group; keep global middleware in `bootstrap/app.php`
+  (or `app/Http/Kernel.php` on codebases still on that structure) rather
+  than duplicating a global concern per-route.
+
+## Formatting
+
+- Follow PSR-12 spacing/brace conventions; run the project's configured
+  formatter (`./vendor/bin/pint` is Laravel's default) instead of
+  hand-formatting around one that is already configured.
+- One class per file, filename matching the class name, matching the
+  namespace to the directory per PSR-4 — do not add a second top-level
+  class/interface/enum to an existing file.

package/src/gdskills/bundled/stacks/php-laravel/rules/patterns.mdc

@@ -0,0 +1,80 @@
+---
+extends: common
+paths: ["**/*.php"]
+metadata:
+  origin: authored
+---
+
+# PHP / Laravel patterns
+
+Narrows `core-common-rules`' stack-agnostic design guidance to idiomatic
+Laravel application design and its common anti-patterns. Applies only to
+`*.php` files.
+
+## Layered responsibility
+
+- Controllers orchestrate; they do not contain business rules. Push
+  non-trivial logic into an Eloquent model method, an invokable action
+  class (`app/Actions/...`), or a service class injected through the
+  constructor.
+- A Form Request class owns validation rules and authorization for one
+  request shape (`rules()`, `authorize()`); do not duplicate the same
+  validation array across multiple controller methods when a shared Form
+  Request would do.
+- Eloquent model classes own their own data shape (casts, relationships,
+  scopes, accessors); keep cross-model orchestration (a multi-model
+  transaction, a workflow spanning several models) in a service or action
+  class, not stuffed into one model's methods.
+
+## Eloquent relationships and queries
+
+- Eager-load a relationship (`with()`, or `load()` after the fact) before
+  iterating a collection and accessing that relationship inside the loop;
+  a relationship accessed per-row with no eager load is an N+1 query, not
+  "just how Eloquent works."
+- For a result set too large to hold in memory, use `chunk()`/`chunkById()`
+  or `cursor()`/`lazy()` instead of `all()`/an unbounded `get()`;
+  `chunkById()` (not plain `chunk()`) when the loop body updates or
+  deletes rows, since plain `chunk()`'s offset pagination skips rows as
+  the underlying set shifts.
+- Use query scopes (`scopeActive`, `scopePublished`) for a filter reused
+  across more than one call site instead of repeating the same `where()`
+  chain.
+
+## Dependency injection and the service container
+
+- Type-hint a constructor/method dependency and let the container resolve
+  it instead of calling `app(SomeClass::class)`/`resolve(...)` inline
+  inside business logic — reserve container-pulling for genuinely
+  dynamic resolution (a class name only known at runtime).
+- Bind an interface to its implementation in a service provider's
+  `register()` when a class needs to be swappable (a payment gateway, a
+  notification channel); do not introduce an interface with exactly one
+  implementation and no swapping need "for testability" alone when
+  Laravel's own container-based mocking (`$this->mock(...)` in tests)
+  already covers that.
+
+## Jobs, events, and idempotency
+
+- A queued job that can be delivered more than once (most production
+  queue connections are at-least-once) either implements `ShouldBeUnique`/`uniqueId()`, or
+  checks/records its own side effect before repeating it — do not assume
+  a job runs exactly once.
+- Prefer a domain event (`event(new OrderShipped($order))`) with
+  dedicated listeners over stacking unrelated side effects directly in
+  the code path that triggers them, when more than one unrelated concern
+  needs to react to the same occurrence.
+
+## Anti-patterns to flag
+
+- A "fat controller" that validates, queries, transforms, and formats the
+  response all inline — split by responsibility as above.
+- A model with `protected $guarded = []` used outside of a factory/seeder
+  context — this disables mass-assignment protection entirely and should
+  be treated as a defect, not a convenience default.
+- Business logic duplicated between a web controller and an API
+  controller for the same underlying action — extract the shared action/
+  service both call.
+- A trait used to share mutable state between unrelated models instead of
+  genuinely shared, stateless behavior — prefer composition (an injected
+  collaborator) when the "shared behavior" is really shared state.

package/src/gdskills/bundled/stacks/php-laravel/rules/security.mdc

@@ -0,0 +1,80 @@
+---
+extends: common
+paths: ["**/*.php"]
+metadata:
+  origin: authored
+---
+
+# PHP / Laravel security
+
+Narrows `core-common-rules`' stack-agnostic security rules to PHP/Laravel-
+specific, OWASP-relevant risks and the framework API to use instead.
+Applies only to `*.php` files.
+
+## Mass assignment
+
+- Every Eloquent model that is ever constructed from request data
+  declares `$fillable` (an explicit allowlist) or `$guarded`; an empty
+  `$guarded = []` mass-assigns every column, attacker-controlled fields
+  (`is_admin`, `role`, `user_id` on someone else's record) included.
+- Build a create/update from `$request->validated()` (the Form Request's
+  validated subset), not raw `$request->all()`/`$request->input()` — even
+  with `$fillable` set, validating first catches type/shape problems
+  `$fillable` alone does not.
+
+## SQL and data access
+
+- Use Eloquent/the query builder's parameter binding
+  (`where('email', $email)`, `DB::select('... where id = ?', [$id])`) for
+  every value that varies with input; never interpolate a variable
+  directly into a raw SQL string (`DB::select("... where id = $id")`,
+  `DB::statement("... = '{$value}'")`) — that is SQL injection regardless
+  of how "internal" the input looks.
+- `DB::raw()`/`whereRaw()`/`selectRaw()` still take bindings as a second
+  argument for any variable part of the expression — pass the value
+  there, not by interpolating it into the raw string.
+
+## Output encoding (Blade/XSS)
+
+- Blade's `{{ $value }}` escapes through `htmlspecialchars` by default;
+  use it for anything that can contain user-influenced content.
+- `{!! $value !!}` performs no escaping — reserve it for content the
+  application itself fully controls and trusts (a sanitized rich-text
+  field explicitly passed through a purifier, not raw user input) and
+  say so at the point of use when it is used at all.
+
+## CSRF and state-changing requests
+
+- Every state-changing route (POST/PUT/PATCH/DELETE) reached from a
+  browser session relies on Laravel's `VerifyCsrfToken`/
+  `ValidateCsrfToken` middleware (the default for the `web` middleware
+  group) and includes `@csrf` in the form or the `X-CSRF-TOKEN`/
+  `X-XSRF-TOKEN` header for an AJAX call.
+- Adding a route to the CSRF-exempt list is a deliberate, narrow decision
+  for a genuinely stateless endpoint (a signed webhook, an API token
+  route already outside the `web` group) — never a workaround for a
+  request that is failing CSRF verification for an unrelated reason.
+
+## Secrets and configuration
+
+- Read secrets from `.env`/`config/*.php` via the `config()` helper; never
+  commit a real credential, API key, or signing secret into a versioned
+  file (`.env.example` gets placeholder values only).
+- Laravel's `APP_KEY` (used for encryption and signed URLs) is generated
+  per environment (`php artisan key:generate`) and never shared between
+  environments or committed to version control.
+
+## Queues and background work
+
+- A queue job handling anything security- or money-relevant is written
+  assuming its connection can redeliver it (true of most production
+  configurations): guard the side effect with
+  `ShouldBeUnique`, a `uniqueId()`, or an idempotency check recorded
+  before the effect runs, not an assumption that retries "shouldn't
+  normally happen."
+
+## Dependency hygiene
+
+- Run `composer audit` when introducing or updating dependencies, or when
+  asked to check for known vulnerabilities in the project's Composer
+  packages.

package/src/gdskills/bundled/stacks/php-laravel/rules/testing.mdc

@@ -0,0 +1,82 @@
+---
+extends: common
+paths: ["**/*.php"]
+metadata:
+  origin: authored
+---
+
+# PHP / Laravel testing
+
+Narrows `core-common-rules`' stack-agnostic testing rules to Laravel's
+testing stack — Pest (the current default for new Laravel apps) or
+PHPUnit, plus Laravel's HTTP/database testing helpers. Applies only to
+`*.php` files.
+
+## Layout and naming
+
+- Tests live under `tests/Feature` (anything touching the framework —
+  HTTP, database, queue, auth) or `tests/Unit` (a class tested in
+  isolation, no framework boot needed); match whichever the project
+  already uses for a given kind of test rather than defaulting one way.
+- Pest: a test file is a plain script of `test('...', function () {...})`/
+  `it('...', function () {...})` calls, optionally grouped with
+  `describe(...)`. PHPUnit: a test class extends `Tests\TestCase`, with
+  each test a `public function test_...(): void` method or a method
+  annotated `#[Test]`.
+- Name a test for the behavior it verifies ("rejects an order with no
+  line items"), not the method under test alone ("test_store").
+
+## Database and factories
+
+- Use model factories (`app/Models/*` + `database/factories/*Factory.php`,
+  `User::factory()->create([...])`) to build test data instead of
+  hand-inserting rows; override only the fields the test cares about.
+- Apply `RefreshDatabase` (or `DatabaseTransactions`, on a project already
+  using it) on any test that touches the database, so each test starts
+  from a known, isolated state — do not rely on execution order between
+  tests for shared fixture data.
+
+## HTTP and feature tests
+
+- Exercise routes through Laravel's HTTP testing helpers
+  (`$this->get(...)`, `$this->postJson(...)`, `actingAs($user)`) and
+  assert on the response (`assertStatus`, `assertJson`, `assertSee`,
+  `assertRedirect`) rather than calling controller methods directly —
+  a feature test should exercise the same path a real request takes
+  (routing, middleware, validation included).
+- Assert authorization/validation failures explicitly
+  (`assertForbidden()`, `assertInvalid(['field'])`) instead of only
+  checking the happy path.
+
+## Fakes over real side effects
+
+- Use Laravel's fakes (`Queue::fake()`, `Mail::fake()`, `Event::fake()`,
+  `Storage::fake('disk')`, `Http::fake([...])`) to assert a job was
+  dispatched, a mail was queued, or an HTTP call was made — never let a
+  test actually send an email, hit a real queue, or make a real outbound
+  HTTP request.
+- After `Queue::fake()`, assert with `Queue::assertPushed(JobClass::class,
+  fn ($job) => ...)` to check the job's own state, not just that some job
+  of that class was pushed.
+
+## Assertions and determinism
+
+- Never synchronize with `sleep()`/a fixed delay to wait for a queued job
+  or async side effect in a test — use `Queue::fake()` and assert what
+  was dispatched, or run the job synchronously in the test
+  (`ShouldQueue` jobs can be dispatched and handled inline via
+  `Bus::fake()`/direct `handle()` invocation) instead of waiting on a
+  real worker.
+- Prefer Pest's `expect($value)->toBe(...)` (or PHPUnit's
+  `assertSame`) over a loose equality check when the type matters (`===`
+  semantics), especially for IDs, enum cases, and money values.
+
+## Static analysis and running
+
+- Run the project's configured static analysis (`./vendor/bin/phpstan
+  analyse`, typically via Larastan on a Laravel app) alongside the test
+  suite when configured — a green test suite with new static-analysis
+  errors is not a finished change.
+- Run `php artisan test` (Pest or PHPUnit, whichever the project uses) or
+  `./vendor/bin/pest`/`./vendor/bin/phpunit` directly; do not skip a slow
+  test file to get a faster local loop without saying so in the report.

package/src/gdskills/bundled/stacks/php-laravel/skills/php-laravel-build-fix/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: php-laravel-build-fix
+description: "Use when composer install/update fails, PHP fatal errors block a Laravel app from booting, phpstan/larastan reports a failing analysis, or a previously-passing test suite is now failing -- resolves dependency conflicts, autoload issues, config/service-provider errors, and static-analysis findings with the smallest root-cause fix. Not for an npm/frontend build failure or a Python/pytest failure (use that stack's own build-fix skill)."
+triggers:
+  - "composer install is failing"
+  - "this Laravel app throws a fatal error on boot"
+  - "phpstan is failing on this file"
+  - "fix this class not found autoload error"
+  - "the service provider isn't registering correctly"
+  - "php artisan test is failing after this change"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# PHP / Laravel build fix
+
+Resolve a `composer install`/`update` failure, a PHP fatal error blocking
+a Laravel app from booting, a `phpstan`/Larastan analysis failure, an
+autoload/class-not-found error, a misconfigured service provider, or a
+newly-failing test suite — with the smallest change that fixes the actual
+root cause. `rules/coding-style.mdc` and `rules/security.mdc` govern what
+a "correct" fix looks like; this skill never reaches for a suppression
+instead of a fix.
+
+## Workflow
+
+### Step 1: Reproduce and classify
+
+```bash
+composer install
+php artisan config:clear && php artisan cache:clear
+./vendor/bin/phpstan analyse   # if configured (Larastan)
+php artisan test
+```
+
+Read the exact error text and classify it:
+
+- **Dependency conflict** (`composer install`/`update` reports a version
+  constraint that cannot be satisfied, or a platform requirement
+  mismatch against the installed PHP version).
+- **Autoload/class-not-found** (`Class "App\..." not found`, usually a
+  PSR-4 namespace/path mismatch, or `composer dump-autoload` needed after
+  a new class).
+- **Boot-time fatal** (a service provider throwing during `register()`/
+  `boot()`, a missing `.env` value a config file requires, a stale cached
+  config/route/view referencing something that moved).
+- **Static-analysis finding** (`phpstan`/Larastan reporting a real type
+  mismatch, an undefined property, or a missing return type).
+- **Test failure** introduced by the change under investigation (not a
+  pre-existing flaky test — confirm by re-running in isolation).
+
+### Step 2: Fix by category
+
+**Dependency conflict:** run `composer why <package>`/`composer why-not
+<package> <version>` before bumping anything by hand; resolve the actual
+constraint mismatch (a package requiring a PHP version, or two packages
+requiring incompatible versions of a shared dependency) rather than
+force-installing with `--ignore-platform-reqs` or blindly widening a
+`composer.json` constraint.
+
+**Autoload/class-not-found:** check the class's namespace matches its
+file path under the PSR-4 mapping in `composer.json`; run `composer
+dump-autoload` after adding a new class if the error persists with a
+correct namespace/path. Do not "fix" this by adding a manual `require`
+for an autoloaded class.
+
+**Boot-time fatal:** read the actual exception and trace it to the
+service provider/config file it originates from; run `php artisan
+config:clear`/`route:clear`/`view:clear` first when the error looks stale
+(references something already renamed/removed) before changing code. Fix
+a missing required `.env` value by documenting it in `.env.example`
+rather than hard-coding a fallback secret in code.
+
+**Static-analysis finding:** fix the type mismatch, missing return type,
+or undefined-property access the finding names. Never add
+`@phpstan-ignore-next-line`/`@psalm-suppress`/a blanket
+`ignoreErrors` entry in `phpstan.neon` to silence a finding without
+addressing what it found.
+
+**Test failure:** read the actual assertion failure; fix the source
+change that broke the contract the test verifies, unless the test itself
+is asserting the wrong thing for a deliberate behavior change (say so in
+the report rather than silently loosening the assertion).
+
+### Step 3: Verify
+
+```bash
+composer install
+./vendor/bin/phpstan analyse   # if configured
+php artisan test
+```
+
+All must exit 0 before reporting done.
+
+### Step 4: Report
+
+```
+Fixed: composer.json version constraint mismatch (guzzlehttp/guzzle)
+  - Root cause: a new dependency required guzzle ^7.8, composer.json pinned ^6.0
+  - composer install / phpstan analyse / php artisan test all pass
+```
+
+State the root cause in one sentence, not just "fixed the error."
+
+## Rules
+
+- Find and fix the smallest change that addresses the actual root cause —
+  never widen a fix beyond what the failure requires.
+- NEVER add `@phpstan-ignore-next-line`, `@psalm-suppress`, or a blanket
+  `ignoreErrors` entry to silence a static-analysis finding instead of
+  fixing what it found.
+- NEVER widen `$fillable` to a catch-all allowlist, or set `$guarded = []`
+  on a model, just to make a mass-assignment error disappear.
+- NEVER install with `--ignore-platform-reqs` to route around a real
+  version conflict without confirming it is an intentional, documented
+  override.
+- NEVER delete or skip a failing test to reach a green build.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll add `@phpstan-ignore-next-line` here so the analysis passes" | Silences the finding without fixing the type mismatch/undefined access it caught; fix the actual code instead |
+| "I'll just run composer with `--ignore-platform-reqs`" | Installs a dependency the running PHP version does not actually satisfy, deferring the real failure to runtime instead of fixing the constraint |
+| "This model's mass-assignment error goes away if I set `$guarded = []`" | Disables mass-assignment protection entirely for every attribute, trading a build error for a security defect |
+| "This test is flaky after my change, I'll skip it for now" | Hides a real regression instead of fixing the change that broke the contract the test verifies |
+
+## Verification
+
+Do not report the fix done until all of the following hold:
+
+- `composer install`, the project's static analysis (if configured), and
+  `php artisan test` all exit 0.
+- The change is the smallest one that addresses the stated root cause —
+  no unrelated files touched.
+- No `@phpstan-ignore-next-line`/`@psalm-suppress`/`ignoreErrors` entry
+  was added to silence a finding.
+- The report states the root cause in one sentence, not just "build now
+  passes."

package/src/gdskills/bundled/stacks/php-laravel/skills/php-laravel-build-fix/evals.json

@@ -0,0 +1,74 @@
+{
+  "triggers": {
+    "positive": [
+      "composer install is failing after I added a new package",
+      "Staging 500s on every request since we swapped in the new Redis session driver",
+      "phpstan is reporting a failure on this file, can you fix it",
+      "Composer dump-autoload runs clean but PHP still can't find App\\Services\\Billing\\InvoiceBuilder at runtime",
+      "I split AppServiceProvider into three smaller providers and now the queue connection singleton isn't bound anymore",
+      "The whole test suite went red with 'could not find driver' right after I bumped the sqlite package version",
+      "Our build is broken because of a dependency version conflict",
+      "Larastan is flagging an undefined property on this model"
+    ],
+    "negative": [
+      "Implement a new endpoint for cancelling an order",
+      "Write Pest tests for the new cancellation endpoint",
+      "Review this diff for mass assignment before merging",
+      "npm run build is failing after a package upgrade in the frontend app",
+      "This Rails app raises a NoMethodError on boot after a gem upgrade",
+      "Fix this failing pytest suite after a dependency update"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "no-phpstan-suppress",
+      "prompt": "phpstan is reporting 'Cannot call method items() on App\\Models\\Order|null' on this line: $order->items()->create([...]). How should I fix it?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer fixes the actual nullability the finding names -- confirming $order can't be null before calling items() on it (e.g. via findOrFail() instead of find(), an explicit null check that returns/throws, or narrowing the parameter/property type) -- rather than silencing the finding with @phpstan-ignore-next-line or a phpstan.neon ignoreErrors entry.",
+          "pass_criteria": [
+            "Names a concrete fix that removes the actual null possibility (e.g. findOrFail() instead of find(), an explicit null guard with an early return/abort, or a non-nullable type on the parameter), not just 'handle the null case'.",
+            "The fix is shown at the point where $order becomes possibly-null (how it was obtained), not just wrapped around the items() call."
+          ],
+          "fail_criteria": [
+            "Recommends adding @phpstan-ignore-next-line, @phpstan-ignore, or a phpstan.neon ignoreErrors entry for this line instead of fixing the underlying nullability. Mentioning phpstan-ignore only to warn against it is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "The finding is real: whatever produced $order can return null (likely Order::find($id) rather than findOrFail($id)), and the code calls ->items()->create([...]) on it without checking. Fix it at the source -- if $order comes from a route/method that should always have a valid order, use Order::findOrFail($id) so a missing order throws a 404 instead of silently producing null; if null is a genuinely valid case here, add an explicit guard (if (! $order) { abort(404); } or return early) before the items() call. Either way phpstan's finding goes away because the type is actually narrowed at that point, not because the checker was told to stop looking.",
+        "known_wrong": "Just add a @phpstan-ignore-next-line comment above that line -- the code works fine at runtime in practice since $order is basically never actually null there, and this is the fastest way to get the analysis passing again without restructuring how the order is fetched.",
+        "vague": "Make sure the nullability is handled properly before calling items() on it.",
+        "subtle_wrong": "Add an inline null-coalescing guard right at the call site: ($order?->items())?->create([...]); -- that satisfies phpstan by narrowing the type at the point of the call, and if $order happens to be null the whole expression just silently evaluates to null instead of throwing, so nothing breaks."
+      },
+      "anti_patterns": ["@phpstan-ignore"]
+    },
+    {
+      "id": "no-guarded-empty-workaround",
+      "prompt": "I'm getting a MassAssignmentException when creating a Product from validated request data -- Product::create($request->validated()) throws because 'category_id' isn't fillable. What's the right fix?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer adds category_id (and only the columns that genuinely need to be mass-assignable) to the Product model's $fillable array, rather than removing mass-assignment protection entirely by setting $guarded = [] or widening $fillable to every column on the table.",
+          "pass_criteria": [
+            "Adds category_id specifically to $fillable (or an equally scoped fix), shown concretely as a code change to the model.",
+            "Keeps the allowlist scoped to only the columns that should be mass-assignable, not every column on the table."
+          ],
+          "fail_criteria": [
+            "Recommends setting $guarded = [] on the Product model, or replacing $fillable with a full list of every table column, to make the exception stop occurring."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "The Product model's $fillable array is missing category_id -- that's exactly what Eloquent's mass-assignment guard is supposed to catch. Fix it by adding the specific column: protected $fillable = ['name', 'price', 'category_id', ...]; (whatever the model already had, plus category_id). That keeps the allowlist scoped to the columns that genuinely need to be set through mass assignment, rather than opening the model up to every column on the table.",
+        "known_wrong": "Just set $guarded = []; on the Product model -- that disables the mass-assignment check entirely so Product::create($request->validated()) will work no matter which columns are present, and you won't run into this exception again for any future field either.",
+        "vague": "Update the model so category_id is allowed to be mass-assigned.",
+        "subtle_wrong": "Replace the model's $fillable array with a list of every column on the products table (id, name, price, category_id, sku, stock, created_at, updated_at, ...) generated from the migration -- that way category_id is covered along with anything else the table might need going forward, without having to keep coming back to update $fillable every time a new field gets added."
+      },
+      "anti_patterns": ["$guarded = []"]
+    }
+  ]
+}