@mrciphersmith/keryx 0.3.0 → 0.3.1

package/src/gdskills/bundled/stacks/nestjs/governance/scout.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Use when building or extending a NestJS module, controller, guard, interceptor, pipe, or exception filter -- choosing provider scope and registering a cross-cutting concern globally via APP_GUARD/APP_INTERCEPTOR/APP_PIPE/APP_FILTER, and keeping controllers thin with business rules delegated downstream. Scoped to authoring new behavior in an app that already boots; excludes selecting field-level checks on a request body, a finished-diff review pass, and diagnosing why an already-written module stops the app from starting.",
+    "decision": "fork",
+    "topMatch": "nestjs/nestjs-testing",
+    "recordedAt": "2026-09-25T06:29:56.288Z",
+    "skillName": "nestjs-implementation",
+    "justification": "Top overlap is review-backend (NestJS DI/guard/controller structure review, not authoring) and mobx-store-review-style patterns are unrelated; closest same-domain skill is review-backend which reviews finished diffs, not implementation, so fork is correct."
+  },
+  {
+    "query": "Use when writing or debugging a NestJS test built through @nestjs/testing: a unit test that compiles a provider via Test.createTestingModule and overrides its collaborators with overrideProvider/overrideGuard/overrideInterceptor, or an e2e test that boots a real Nest application and drives it with supertest through the actual guard/pipe/filter pipeline. Scoped to a test compiled through Nest's own testing module builder; excludes picking field-level checks for a request body, authoring the feature itself, and a plain unit test with no Nest module wiring involved.",
+    "decision": "fork",
+    "topMatch": "nestjs/nestjs-implementation",
+    "recordedAt": "2026-09-25T06:30:10.502Z",
+    "skillName": "nestjs-testing",
+    "justification": "Top overlap is nestjs-implementation (same pack, different category, not a substitute) and review-backend/review-testing-practices review finished diffs rather than authoring @nestjs/testing specs, so fork is correct."
+  },
+  {
+    "query": "Use when a NestJS app itself won't boot because of its own dependency graph: `Nest can't resolve dependencies` / UnknownDependenciesException, a circular-dependency warning between modules or providers, a missing @Injectable() decorator, or a provider that isn't exported from the module owning it. Applies the smallest root-cause fix to the module/provider graph and never widens scope or adds a module import blindly to silence the startup failure. Excludes a TypeScript compiler mismatch or module-loader failure with no Nest dependency-injection angle at all (use the ts-js-node build-fix skill), and excludes authoring behavior in a module that already boots cleanly (use nestjs-implementation).",
+    "decision": "fork",
+    "topMatch": "angular/angular-build-fix",
+    "recordedAt": "2026-09-25T06:30:16.866Z",
+    "skillName": "nestjs-build-fix",
+    "justification": "Top overlap is nodejs-build-fix (ts-js-node pack, generic tsc/module-resolution errors, not Nest's own DI graph) and nestjs-implementation (same pack, authoring not fixing); neither substitutes for diagnosing UnknownDependenciesException/circular-module errors, so fork is correct."
+  },
+  {
+    "query": "Use when writing or debugging a NestJS test built through Nest's own testing-module builder: a unit test that swaps a provider's real dependency (a repository, an HTTP client) for a fake or mock double so the unit under test runs in isolation, or an e2e test that boots a real Nest application and drives it with supertest through the actual guard/pipe/filter pipeline. Scoped to a test compiled through Nest's own testing module; excludes picking field-level checks for a request body, authoring the feature itself, and a framework-agnostic unit test that never touches Nest's module system.",
+    "decision": "create",
+    "topMatch": "nestjs/nestjs-implementation",
+    "recordedAt": "2026-09-25T06:33:27.947Z",
+    "skillName": "nestjs-testing",
+    "justification": "Top overlap remains nestjs-implementation (same pack, different category, authoring not testing) and review-backend/review-testing-practices review finished diffs rather than authoring @nestjs/testing specs, so fork is correct."
+  }
+]

package/src/gdskills/bundled/stacks/nestjs/pack.json

@@ -0,0 +1,53 @@
+{
+  "id": "nestjs",
+  "family": "framework",
+  "extends": "ts-js-node",
+  "modules": [
+    "nestjs-rules",
+    "nestjs-skills"
+  ],
+  "detectionMarkers": [
+    "nestjs"
+  ],
+  "provenance": {
+    "origin": "authored",
+    "sourceRef": "flow 318, Wave 4 batch 2"
+  },
+  "stability": "experimental",
+  "skills": {
+    "implement": [
+      "nestjs-implementation"
+    ],
+    "test": [
+      "nestjs-testing"
+    ],
+    "review": [],
+    "build-fix": [
+      "nestjs-build-fix"
+    ],
+    "migrate": []
+  },
+  "agentProfile": {
+    "displayName": "NestJS",
+    "auditFocus": [
+      "a REQUEST-scoped or TRANSIENT provider injected into a Singleton provider, sharing one request's state across others",
+      "a guard, interceptor, or pipe re-implemented per-controller instead of reused via APP_GUARD/APP_INTERCEPTOR/APP_PIPE or a shared decorator",
+      "business logic or direct ORM/repository calls inside a controller method instead of delegated to a service",
+      "a circular dependency between two modules or providers with no forwardRef(), or a provider resolved by string token with no matching provide entry",
+      "an exception filter or async controller method that lets an unhandled rejection or a raw internal error reach the HTTP response",
+      "a custom decorator or Reflector-based metadata read with no default when the metadata key is absent"
+    ],
+    "buildCommands": [
+      "nest build (or the project's package.json build script wrapping it)",
+      "tsc --noEmit",
+      "the project's lint script (eslint . or npm run lint)",
+      "the project's test script (nest test / jest, including e2e: npm run test:e2e)"
+    ],
+    "fixGuardrails": [
+      "Never widen a provider's scope to Default/Singleton just to make a DI resolution error disappear without checking whether the provider genuinely needs request-scoped state.",
+      "Never add a module to `imports` purely to silence an UnknownDependenciesException without confirming that module actually exports the provider being injected.",
+      "Never catch and swallow an exception in a controller or service just to stop a NestJS unhandled-rejection warning; use a proper exception filter or rethrow a typed HttpException.",
+      "Never delete or skip a failing @nestjs/testing spec to reach a green build."
+    ]
+  }
+}

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

@@ -0,0 +1,70 @@
+---
+extends: common
+paths: ["**/*.ts"]
+metadata:
+  origin: authored
+---
+
+# NestJS coding style
+
+Narrows `core-common-rules`' stack-agnostic style rules, and `ts-js-node`'s
+own TypeScript conventions, to NestJS's own idiom: decorator-driven modules,
+providers, and dependency injection. Applies only to `*.ts` files in a
+NestJS project.
+
+## Naming and file layout
+
+- One artifact per file, named after its role: `<name>.controller.ts`,
+  `<name>.service.ts`, `<name>.module.ts`, `<name>.dto.ts`,
+  `<name>.guard.ts`, `<name>.interceptor.ts`, `<name>.filter.ts`,
+  `<name>.pipe.ts` — the Nest CLI's own generator convention. Do not fold a
+  guard or interceptor into a controller file "since it's only used there".
+- Class names end in the same suffix as the file role
+  (`UsersController`, `UsersService`, `UsersModule`), `PascalCase`.
+- Injection tokens for non-class providers (`useValue`/`useFactory`) are
+  `UPPER_SNAKE_CASE` string constants or `Symbol()`s exported from a single
+  `tokens.ts`/`constants.ts`, never an inline string literal repeated at
+  every injection site.
+
+## Decorators and typing
+
+- Every constructor-injected dependency is typed explicitly
+  (`constructor(private readonly usersService: UsersService) {}`); do not
+  widen an injected dependency to `any` to sidestep a circular-import type
+  error — fix the import cycle instead (see `rules/patterns.mdc`).
+- Every controller method's return type is explicit or trivially inferred
+  from a typed service call — never `Promise<any>`.
+- DTOs are typed classes with `class-validator`/`class-transformer`
+  decorators, never plain `interface`s for request bodies — interfaces are
+  erased at runtime and `ValidationPipe` has nothing to validate against
+  (see `rules/security.mdc` and the repo's own `nestjs-dto.mdc` rule, which
+  owns the full DTO decorator checklist).
+- Use `@Injectable()` on every class that is registered as a provider, even
+  a class with no constructor dependencies — omitting it is a common cause
+  of a confusing DI resolution failure covered in
+  `skills/nestjs-build-fix/SKILL.md`.
+
+## Imports and module boundaries
+
+- Import providers only from the module that exports them; do not reach
+  into another feature module's `src/<feature>/*.service.ts` file directly
+  — import the feature module and let Nest's DI resolve it, or add the
+  provider to that module's `exports` array if it is meant to be shared.
+- Keep a module's `providers`, `controllers`, `imports`, and `exports`
+  arrays sorted by the order they were added or grouped logically; do not
+  let an `@Module()` decorator grow past what fits on one screen without
+  splitting the feature into sub-modules.
+- Barrel files (`index.ts` re-exporting a feature's public surface) export
+  only what other modules are meant to import — not internal providers,
+  guards, or DTOs used solely inside the module.
+
+## Errors
+
+- Throw a specific built-in NestJS exception (`NotFoundException`,
+  `BadRequestException`, `ConflictException`, etc.) or a project-defined
+  subclass of `HttpException`, never a bare `throw new Error(...)` from a
+  controller or service that is expected to produce an HTTP response — a
+  plain `Error` becomes an opaque `500` with no semantic status code.
+- Do not catch an exception in a service only to log it and rethrow the
+  same thing unchanged; catch only where you add context (wrap with a
+  domain-specific exception) or where you genuinely handle it.

package/src/gdskills/bundled/stacks/nestjs/rules/patterns.mdc

@@ -0,0 +1,83 @@
+---
+extends: common
+paths: ["**/*.ts"]
+metadata:
+  origin: authored
+---
+
+# NestJS patterns
+
+Idiomatic module/provider/request-pipeline design for NestJS, and the
+anti-patterns that recur in Nest codebases specifically. Applies only to
+`*.ts` files in a NestJS project; general TypeScript design guidance still
+comes from `ts-js-node`'s own rules.
+
+## Module and provider design
+
+- A feature module owns its controllers, services, and the providers those
+  services need; it imports other feature modules only for the providers
+  it actually consumes, and exports only what other modules are meant to
+  inject.
+- Break a real circular dependency between two modules with `forwardRef()`
+  on both sides of the `imports`/`providers` reference — but treat
+  `forwardRef()` as a signal to reconsider the boundary first: a genuine
+  circular need between two feature modules is often better modeled as a
+  shared third module both depend on.
+- Prefer constructor injection over property injection (`@Inject()` on a
+  class field) except where a truly optional dependency needs
+  `@Optional()` — constructor injection makes required dependencies
+  visible in the type signature and fails fast at module-compile time.
+- Default provider scope (`Default`/Singleton) is correct for stateless
+  services. Reach for `Scope.REQUEST` only when the provider genuinely
+  needs per-request state (e.g. the current user from a request-scoped
+  `REQUEST` token); a `REQUEST`-scoped provider re-instantiates its entire
+  injection subtree per request, which has a real performance cost — do
+  not default to it "to be safe."
+
+## Guards, interceptors, pipes, and filters
+
+- Cross-cutting concerns (auth, logging, response shaping, validation)
+  belong in a guard/interceptor/pipe/filter, not duplicated inline in every
+  controller method that needs it.
+- Register a cross-cutting concern that applies to (nearly) every route as
+  a global provider via `APP_GUARD`/`APP_INTERCEPTOR`/`APP_PIPE`/
+  `APP_FILTER` in a module's `providers` array (this keeps it inside Nest's
+  DI graph, unlike `app.useGlobalGuards()` called on the bootstrapped
+  instance), not by decorating every controller by hand.
+- When a global guard protects most routes, mark the exceptions explicitly
+  with a custom decorator read via `Reflector` (e.g. `@Public()`) rather
+  than leaving some controllers undecorated and hoping the guard's default
+  is safe — an undecorated route should never be silently open just
+  because the guard's fallback happens to allow it.
+- A guard, interceptor, or pipe class stays free of business logic: a guard
+  decides allow/deny, an interceptor transforms/observes the
+  request-response stream, a pipe transforms/validates one argument. Move
+  any decision that needs several service calls into the service layer and
+  have the guard call that service.
+
+## Controllers vs. services
+
+- A controller method parses/validates input (via DTO + `ValidationPipe`),
+  delegates to exactly one service call for the actual work, and shapes
+  the HTTP response — it does not call a repository/ORM directly, does not
+  branch on business rules, and does not orchestrate multiple service
+  calls that a service method could compose instead.
+- A service method has an explicit return type and throws a Nest HTTP
+  exception (see `rules/coding-style.mdc`) or a domain error the caller
+  translates — it never imports `Request`/`Response` from the HTTP
+  framework except for a documented streaming/file-download case.
+
+## Anti-patterns to avoid
+
+- Injecting the whole `ModuleRef` or reaching for
+  `moduleRef.get(Provider, { strict: false })` to route around a missing
+  `imports`/`exports` entry — fix the module graph instead; a lazy
+  `ModuleRef.get` lookup hides a real DI wiring mistake.
+- A provider registered with `useValue`/`useFactory` whose factory has side
+  effects beyond constructing the value (e.g. opening a connection with no
+  corresponding `OnModuleDestroy` cleanup) — pair any resource-acquiring
+  factory provider with the matching lifecycle hook.
+- Business rules encoded only as `@Roles()`/`@Permissions()` decorator
+  strings scattered per-endpoint with no single source of truth for what
+  each role can do — centralize the role/permission matrix so a guard
+  reads it instead of re-deriving it per route.

package/src/gdskills/bundled/stacks/nestjs/rules/security.mdc

@@ -0,0 +1,73 @@
+---
+extends: common
+paths: ["**/*.ts"]
+metadata:
+  origin: authored
+---
+
+# NestJS security
+
+Stack-specific request-pipeline risks for a NestJS application — where an
+unvalidated or unauthorized request can reach application code — narrowing
+the OWASP-style guidance in the common rules. Applies only to `*.ts` files
+in a NestJS project; SQL/ORM-specific injection risk is covered by the
+`review-backend` skill and the project's ORM rules, not duplicated here.
+
+## Input validation
+
+- Every controller method that accepts a body, query, or route param has a
+  typed DTO class validated by a global `ValidationPipe` (registered once,
+  in `main.ts` via `app.useGlobalPipes(new ValidationPipe(...))`, or as an
+  `APP_PIPE` provider) — a per-controller `@UsePipes(ValidationPipe)` that
+  some controllers omit is the same gap as no `ValidationPipe` at all for
+  the endpoints that skip it.
+- Enable `whitelist: true` (strip unknown properties) and
+  `forbidNonWhitelisted: true` (reject a request carrying an unknown
+  property) on the global `ValidationPipe` — without them, a DTO's
+  `class-validator` decorators only validate the fields they name; any
+  extra field the client sends still reaches the handler untouched.
+- Never trust a query/param value's type from the route alone — a route
+  param typed `id: string` in the controller signature is still a raw
+  string at runtime; convert and validate it (`ParseIntPipe`,
+  `ParseUUIDPipe`, or a DTO with `@IsInt()`/`@IsUUID()`) rather than
+  passing it straight to a repository call.
+
+## AuthN/AuthZ
+
+- Protect every route that must not be public with a guard
+  (`@UseGuards(...)` or a global `APP_GUARD`); a route with neither a guard
+  nor an explicit `@Public()`-style marker is not provably intentional —
+  treat an undecorated route in an otherwise-guarded controller as a gap to
+  confirm, not assume-safe.
+- Read the authenticated principal from the guard-populated request object
+  (e.g. a custom `@CurrentUser()` param decorator backed by
+  `request.user`) — never from a client-supplied header, body field, or
+  query param that claims who the caller is.
+- A role/permission check belongs in a guard evaluated before the handler
+  runs, not as an `if` inside the service after data has already been
+  fetched or mutated.
+
+## Response and error handling
+
+- An exception filter (global `APP_FILTER`, or `app.useGlobalFilters(...)`)
+  must translate an unexpected internal error into a generic response —
+  never let a raw `error.message`/`error.stack` from an ORM, an HTTP
+  client, or an uncaught exception reach the HTTP response body; that
+  leaks internal schema, file paths, or connection details to the caller.
+- Use NestJS's built-in `HttpException` subclasses (or your own subclass of
+  `HttpException`) for expected error conditions so the status code and
+  the response shape stay in the framework's own exception-filter
+  pipeline, instead of manually setting `response.status(...)` in a
+  controller and bypassing filters.
+
+## Secrets and configuration
+
+- Read secrets (API keys, DB credentials, JWT signing keys) through
+  `ConfigService`/`@nestjs/config`, never hardcoded in a provider or
+  committed default value — a `useFactory` provider that falls back to a
+  literal secret when an env var is unset is the same risk as hardcoding
+  it.
+- Do not log a full request/response body in an interceptor or middleware
+  applied globally without redacting known-sensitive DTO fields (passwords,
+  tokens, card numbers) — a broad request logger is a common accidental
+  secret-leak path into log storage.

package/src/gdskills/bundled/stacks/nestjs/rules/testing.mdc

@@ -0,0 +1,69 @@
+---
+extends: common
+paths: ["**/*.ts"]
+metadata:
+  origin: authored
+---
+
+# NestJS testing
+
+Test layout and conventions specific to `@nestjs/testing`, narrowing
+`ts-js-node`'s general test-runner guidance to Nest's module-compiled test
+style. Applies only to `*.ts` files in a NestJS project.
+
+## Layout and runner
+
+- Unit tests for a provider live beside it as `<name>.service.spec.ts` /
+  `<name>.controller.spec.ts`; end-to-end tests live under `test/` as
+  `<feature>.e2e-spec.ts`, matching the Nest CLI's own generated layout and
+  its default `test/jest-e2e.json` config.
+- Run the project's own `package.json` test scripts (typically `test` for
+  unit specs and `test:e2e` for the `test/` suite) rather than invoking
+  `jest`/`vitest` directly with ad hoc flags — they carry the project's own
+  module resolution and coverage config.
+
+## Building the test module
+
+- Build the unit under test through `Test.createTestingModule({...}).compile()`
+  from `@nestjs/testing`, not by `new`-ing the class directly with hand-built
+  fake dependencies — a hand-built instance skips Nest's own DI wiring and
+  can pass while the real module graph would fail to compile.
+- Replace a real dependency with a test double via `.overrideProvider(Token)
+  .useValue(...)` (or `.useFactory(...)`/`.useClass(...)`) on the
+  `TestingModule` builder, not by monkey-patching the class prototype or
+  mutating an already-compiled module's internals.
+- For a guard/interceptor/pipe/filter under test in isolation, override it
+  the same way (`overrideGuard`/`overrideInterceptor`/`overridePipe`/
+  `overrideFilter`) rather than constructing it manually when it depends on
+  injected providers (e.g. `Reflector`).
+- For an e2e spec, call `moduleRef.createNestApplication()` then
+  `app.init()` before issuing requests, and `app.close()` in `afterAll` —
+  a suite that never calls `app.close()` leaks open handles (DB
+  connections, timers) across spec files and can make later suites hang or
+  flake.
+
+## Mocking and fixtures
+
+- Mock at the provider boundary (repository/HTTP-client provider), not by
+  stubbing a private method on the real service under test — the point of
+  `overrideProvider` is to replace what the unit depends on, not to reach
+  inside it.
+- Build a request-scoped dependency's test double as a plain object/mock
+  matching its public shape (`{ findAll: jest.fn() }`), not the real
+  provider with `Scope.REQUEST` instantiated per test — request scope only
+  matters at the framework's request-handling boundary, which a unit test
+  bypasses entirely.
+- Use `supertest` against `app.getHttpServer()` for e2e assertions on
+  status code and response shape; do not assert against the service's
+  return value directly in an e2e spec — that turns the e2e test back into
+  a unit test and loses the point of exercising the real HTTP pipeline
+  (guards, pipes, filters included).
+
+## Determinism
+
+- Reset or recreate mocked providers between tests (`jest.clearAllMocks()`
+  in `afterEach`, or a fresh `TestingModule` per test) so one spec's mock
+  call count or return value cannot leak into the next.
+- Do not depend on Nest's module compile order across a test file; each
+  `describe` block that needs a `TestingModule` builds and compiles its
+  own rather than sharing one built in an outer, unrelated `describe`.

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

@@ -0,0 +1,157 @@
+---
+name: nestjs-build-fix
+description: "Use when a NestJS app itself won't boot because of its own dependency graph: `Nest can't resolve dependencies` / UnknownDependenciesException, a circular-dependency warning naming @Module()-decorated NestJS modules or @Injectable() providers requiring each other directly, a missing @Injectable() decorator, or a provider that isn't exported from the module owning it. Applies the smallest root-cause fix to the module/provider graph and never widens scope or blindly registers another module to silence the startup failure. Excludes a TypeScript compiler mismatch or module-loader failure with no Nest dependency-injection angle at all (use the ts-js-node build-fix skill), and excludes authoring behavior in a module that already boots cleanly (use nestjs-implementation)."
+triggers:
+  - "Nest can't resolve dependencies of this provider"
+  - "fix this NestJS UnknownDependenciesException"
+  - "these two NestJS modules have a circular dependency on each other"
+  - "NestJS app won't bootstrap, dependency injection error"
+  - "this provider isn't found, NestJS DI error"
+  - "NestJS app throws at startup over its own module graph"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# NestJS build-fix (DI resolution / circular dependency / bootstrap errors)
+
+Resolve a NestJS-specific compile or startup failure in the module/provider
+dependency graph -- not a generic `tsc` type error (see the `ts-js-node`
+build-fix skill for that). Applies the smallest change that fixes the
+actual root cause in the module graph. See `rules/patterns.mdc` for the
+module/provider design a correct fix should restore.
+
+## Workflow
+
+### Step 1: Reproduce the failure
+
+```bash
+npx tsc --noEmit
+nest build
+npm run start:dev
+```
+
+Run the project's own `package.json` build/start scripts if they differ.
+Most Nest DI errors only surface at **application bootstrap**, not at
+`tsc` type-check time -- `tsc --noEmit` can pass while the app still fails
+to start with an `UnknownDependenciesException`. Capture the exact error
+message: it names the provider that could not be resolved and, often, the
+module Nest was trying to resolve it inside.
+
+### Step 2: Classify the failure
+
+- **`UnknownDependenciesException` / "Nest can't resolve dependencies of
+  X"**: a provider's constructor asks for a dependency Nest cannot find in
+  the current module's own providers or its imported modules' exports.
+- **Circular dependency warning**: two modules (or two providers) depend on
+  each other, forming a cycle Nest cannot resolve without `forwardRef()`.
+- **Missing `@Injectable()`**: a class used as a provider or injected as a
+  dependency has no `@Injectable()` decorator, so Nest cannot construct it
+  through DI at all -- a different failure shape from the two above, often
+  reported as the same "can't resolve dependencies" message.
+- **Bootstrap failure with no clear provider name**: often a lifecycle hook
+  (`OnModuleInit`) throwing during app startup, not a DI graph problem at
+  all -- check the actual thrown error before assuming it's a wiring issue.
+
+### Step 3: Find the root cause
+
+**Unknown dependency**: read the exact index Nest reports (it names which
+constructor argument position failed) and trace that dependency back to its
+own `@Injectable()`/provider declaration. Check three things in order: (1)
+is the dependency listed in the current module's `providers`? (2) if it
+lives in another module, is that module in the current module's `imports`,
+**and** does that other module `export` the provider? (3) is the injected
+class itself decorated with `@Injectable()`?
+
+**Circular dependency**: identify the two modules or providers that
+reference each other. Confirm it is a genuine mutual need, not an
+accidental import that could instead go one direction -- see
+`rules/patterns.mdc` on treating `forwardRef()` as a signal to reconsider
+the boundary first.
+
+**Missing `@Injectable()`**: check the class definition directly; a class
+with no decorator that is still listed in `providers` or injected
+elsewhere is the exact shape of this failure.
+
+### Step 4: Apply the smallest correct fix
+
+- Missing export: add the provider to the owning module's `exports` array
+  -- do not instead re-declare the same provider in the consuming module's
+  own `providers` array, which creates two separate instances of what
+  should be one shared provider.
+- Missing import: add the owning module to the consuming module's
+  `imports` array -- only after confirming the provider is actually
+  exported from it (step 3); adding the import alone does not fix a
+  missing export.
+- Genuine circular dependency: apply `forwardRef()` on **both** sides of
+  the reference (the module-level `imports: [forwardRef(() => OtherModule)]`
+  and, if it's providers rather than modules, the constructor parameter's
+  `@Inject(forwardRef(() => OtherService))`) -- one-sided `forwardRef()`
+  does not resolve a genuine cycle.
+- Missing `@Injectable()`: add the decorator to the class.
+- A lifecycle-hook throw: fix the actual condition it's failing on (e.g. a
+  config value that's genuinely missing), not by swallowing the exception
+  inside the hook.
+
+### Step 5: Verify and report
+
+Re-run the exact command from Step 1 (the app must actually boot, not just
+type-check) and confirm no DI/circular-dependency warning appears in the
+startup log. Report the root cause and the fix, not just "resolved".
+
+```
+Fixed: src/orders/orders.module.ts
+  Root cause: OrdersService injects PricingService, but PricingModule
+  never exported PricingService -- it was only declared in PricingModule's
+  own `providers` array.
+  Fix: added PricingService to PricingModule's `exports` array.
+  Verified: npm run start:dev boots with no UnknownDependenciesException.
+```
+
+## Rules
+
+- Follow `rules/patterns.mdc` for the module/provider design a fix should
+  restore, not just silence.
+- ALWAYS fix the actual module-graph gap (missing export/import/decorator,
+  or a genuine `forwardRef()` cycle) -- never widen the fix beyond the
+  module(s) the failure actually touches.
+- NEVER change a provider's scope (e.g. to `Scope.DEFAULT`) just to make a
+  resolution error disappear without confirming the provider doesn't
+  genuinely need request-scoped state.
+- NEVER add a module to another module's `imports` purely to silence an
+  `UnknownDependenciesException` without first confirming that module
+  actually `export`s the provider being injected -- an import with no
+  matching export does not fix the error and just adds noise to the graph.
+- NEVER re-declare the same provider in a second module's own `providers`
+  array as a workaround for a missing `exports` entry -- that creates two
+  separate instances of what the codebase intends to be one shared
+  provider.
+- NEVER delete or skip a failing test to reach a green build.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just add PricingModule to imports, that usually fixes these" | Without confirming PricingModule actually exports PricingService, the import alone does nothing -- verify the export exists before adding the import |
+| "I'll re-declare PricingService in this module's own providers instead of fixing the export" | Creates a second, separate instance of the provider instead of sharing the one PricingModule owns -- state and side effects diverge silently |
+| "I'll wrap just the failing side in forwardRef() and leave the other side as a normal import" | A genuine cycle needs forwardRef() on both sides; a one-sided fix still resolves in the wrong order and fails the same way |
+| "This OnModuleInit hook throws, I'll wrap it in try/catch and swallow the error" | Bootstrap fails for a reason -- swallowing it lets the app start in a broken state instead of surfacing what's actually missing (e.g. a required config value) |
+
+## Verification
+
+Do not report the fix done until all of the following hold:
+
+- The app actually boots (`npm run start:dev` or the project's equivalent)
+  with no DI resolution error or circular-dependency warning, not just
+  that `tsc --noEmit` exits 0.
+- No provider's scope was changed, and no module/provider was duplicated,
+  as a workaround.
+- Every `forwardRef()` added for a genuine cycle appears on both sides of
+  the reference.
+- The report states the actual root cause (missing export, missing
+  decorator, genuine cycle) and the fix, not just "DI error fixed".
+- `git status` shows changes confined to the module(s)/provider(s) the
+  root cause required.

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

@@ -0,0 +1,70 @@
+{
+  "triggers": {
+    "positive": [
+      "Nest can't resolve dependencies of OrdersService, help me fix this",
+      "Our NestJS app crashes at bootstrap with a dependency-injection stack trace naming OrdersService's constructor -- Nest cannot resolve it.",
+      "There's a circular dependency warning between UsersModule and AuthModule",
+      "Something in OrdersService's constructor keeps our NestJS app from finishing bootstrap -- Nest reports it cannot resolve the dependency.",
+      "Our NestJS app cannot bootstrap because Nest cannot resolve a dependency OrdersService needs -- what does the DI error at constructor index [2] actually mean?",
+      "Fix this NestJS build error that's blocking npm run start:dev"
+    ],
+    "negative": [
+      "Write unit tests for UsersService using @nestjs/testing with a mocked repository",
+      "Add a new NestJS module for the invoices feature with a controller and service",
+      "Fix this plain tsc error: Type 'string' is not assignable to type 'number' in a Node script",
+      "Review this NestJS PR for missing DTO validation and N+1 queries",
+      "go vet ./... is failing on this package, help resolve the compile error",
+      "Fix this Angular AOT compile error about an unresolved template reference"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "missing-export-not-import-alone",
+      "prompt": "OrdersService injects PricingService and Nest throws an UnknownDependenciesException naming OrdersService at bootstrap. I already added PricingModule to OrdersModule's imports array, but it's still failing. What am I missing?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer identifies that adding PricingModule to OrdersModule's imports is not enough by itself: PricingModule must also list PricingService in its own exports array, since only exported providers are visible to importing modules. The fix is adding PricingService to PricingModule's exports array, not re-declaring PricingService inside OrdersModule's own providers.",
+          "pass_criteria": [
+            "States that importing PricingModule only makes it visible to OrdersModule if PricingModule actually exports PricingService -- an import with no matching export entry does not resolve the dependency",
+            "Names the concrete fix: add PricingService to PricingModule's exports array"
+          ],
+          "fail_criteria": [
+            "Recommends re-declaring PricingService directly inside OrdersModule's own providers array as the fix, instead of adding it to PricingModule's exports -- that creates a second, separate instance of the provider rather than sharing the one PricingModule owns"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Importing PricingModule only gets you access to what it actually exports -- if PricingService is declared in PricingModule's providers but not listed in its exports array, OrdersModule still can't see it even though the module itself is imported. Check PricingModule's @Module() decorator:\n\n@Module({\n  providers: [PricingService],\n  exports: [PricingService], // <- this is almost certainly missing\n})\nexport class PricingModule {}\n\nAdd PricingService to that exports array. That's the fix -- OrdersModule's imports entry was already correct, the gap was on PricingModule's side.",
+        "known_wrong": "If the import isn't picking it up, just add PricingService directly to OrdersModule's own providers array too, alongside OrdersService. That guarantees it's available in OrdersModule's DI container regardless of what PricingModule does or doesn't export.",
+        "vague": "Double check that PricingModule is actually sharing PricingService properly with other modules that need it.",
+        "subtle_wrong": "Add PricingService to PricingModule's exports, and also add it to OrdersModule's own providers array just to be safe in case the export doesn't propagate correctly -- that way OrdersService can resolve it either way."
+      }
+    },
+    {
+      "id": "circular-dependency-both-sides",
+      "prompt": "OrdersModule and PricingModule genuinely need providers from each other. I added forwardRef() to OrdersModule's imports array, but PricingModule still throws a circular dependency error at bootstrap. What's wrong?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer explains that resolving a genuine circular dependency with forwardRef() requires it on both sides of the reference, not just one -- OrdersModule's forwardRef() alone still leaves PricingModule trying to resolve OrdersModule the normal way, which fails the same way. The fix is adding forwardRef(() => OrdersModule) to PricingModule's imports as well (and the matching @Inject(forwardRef(...)) on constructor parameters if the cycle is between providers, not just modules).",
+          "pass_criteria": [
+            "States that forwardRef() must be applied on both sides of a genuine circular reference, and that having it only in OrdersModule's imports is why PricingModule still fails",
+            "Names the concrete fix: add forwardRef(() => OrdersModule) to PricingModule's own imports array (and @Inject(forwardRef(() => OtherService)) on the relevant constructor parameter if the providers themselves reference each other)"
+          ],
+          "fail_criteria": [
+            "Recommends removing forwardRef() and instead reordering the modules' imports, or merging the two modules, as the fix -- rather than applying forwardRef() symmetrically on both sides of the genuine cycle"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "forwardRef() has to be on both sides of a genuine cycle -- putting it only in OrdersModule's imports fixes how OrdersModule resolves PricingModule, but PricingModule is still trying to resolve OrdersModule the normal, eager way, which fails for the same reason. Add it symmetrically:\n\n// pricing.module.ts\n@Module({\n  imports: [forwardRef(() => OrdersModule)],\n})\nexport class PricingModule {}\n\nIf the cycle is actually between the two services rather than just the modules (PricingService injects OrdersService or vice versa), the constructor also needs @Inject(forwardRef(() => OrdersService)) on that parameter, since module-level forwardRef() alone doesn't cover a provider-level cycle. Once both sides use forwardRef(), the app should bootstrap.",
+        "known_wrong": "Circular deps between modules are usually a sign forwardRef() is the wrong tool -- just remove it from OrdersModule's imports and instead reorder which module gets imported first in AppModule, since import order sometimes resolves it without needing forwardRef at all.",
+        "vague": "Circular dependencies in NestJS usually need forwardRef on both modules that reference each other, so make sure it's applied consistently.",
+        "subtle_wrong": "Add forwardRef(() => OrdersModule) to PricingModule's imports too, but skip the @Inject(forwardRef(...)) on the constructor parameter -- the module-level forwardRef should be enough to cover the provider injection as well, so there's no need to duplicate it at the constructor level."
+      }
+    }
+  ]
+}