The AI harness for AdonisJS

# Authorization: Inertia React

## Recommended Defaults
- Identify the subject first. Global apps
  use User. Scope-membership apps use
  the membership entity, TeamMember or
  OrgMember.
- Define permissions in start/permissions.ts
  via definePermissions(...). Export
  PermissionKey for type-safe references.
- Apply middleware.authorize('key') on the
  route for pure permission-key gates. No
  bouncer.* call in the controller.
- For ownership or conditional state, use a
  Bouncer policy. Gate the key first, then
  check the runtime condition.
- Authorize before validating. Call bouncer
  before request.validateUsing(...).

## Avoid by default
- Encoding ownership in permission keys. No
  post.editOwn. Use a Bouncer policy.
- Inlining ownership checks in controllers.
- Hardcoding permission keys outside
  permissions.getKey(...).

# Controllers: Inertia React

## Recommended Defaults
- Scaffold via node ace make:controller.
  One class per file, default-exported as
  <Name>Controller.
- Type actions with HttpContext first.
  Destructure only what the action needs.
- Wire routes via [controllers.<Name>, 'action']
  from #generated/controllers. The barrel
  is auto-maintained.
- Validate at the controller boundary with
  request.validateUsing(<validator>).
- Form submissions end with session.flash(...)
  then response.redirect().toRoute(name).

## Avoid by default
- Reading the request body via request.all()
  or request.input(...). Use validateUsing.
- Generating a resource controller for one or
  two unrelated actions.
- Splitting one resource into two router.resource
  calls to separate public and gated actions.
  Apply per-action middleware on a single
  resource call instead.

# Frontend: Inertia React

## Recommended Defaults
- Generate every page with
  node ace make:page <path>.
- Type page props with InertiaProps<{...}>
  from ~/types. Reference transformer shapes
  via Data.<Resource> from @generated/data.
  Never redeclare inline.
- Navigate with <Link route="..." routeParams={...}>
  from @adonisjs/inertia/react. Method derives
  from the route. Never pass method.
- Submit with <Form route="...">. Render-prop
  API exposes errors, processing, progress.
- Validation errors propagate from server flash.
  Never duplicate Vine validators on the page.
- Encode filters and pagination in the URL
  query string. Do not mirror into useState.

## Invalid patterns
- Importing Link or Form from @inertiajs/react.
  Use @adonisjs/inertia/react.
- Installing react-router, @tanstack/react-router,
  or any client router. Inertia handles routing.
- Introducing redux, zustand, jotai, recoil,
  or any global store for server-derived data.
  Controller props are the source of truth.
- useEffect + fetch to load page data. Use
  inertia.render props instead.

# Middleware

## Recommended Defaults
- Use server.use([...]) for middleware that
  must run on every HTTP request, even when
  no route matches.
- Use router.use([...]) for middleware that
  should run only after a route matches.
- Use export const middleware = router.named({...})
  for route-level middleware applied via .use().
- Lazy-import middleware files via
  () => import('#middleware/...').
- Type handlers with HttpContext first and
  NextFn second.
- Put pre-handler logic before await next().
  Put post-handler logic after.

## Invalid patterns
- Injecting dependencies as extra handle(...)
  parameters. DI is constructor-only.
- Registering middleware classes directly in
  start/kernel.ts without lazy import.
- Defining named middleware inline inside
  start/routes.ts.

# Transactions

## Recommended Defaults
- Default to db.transaction(async (trx) => ...).
  Returns the callback's value, rethrows on
  rollback.
- Build every query off trx, never db.
  Queries through db inside the callback
  run outside the transaction and commit
  immediately.

  await db.transaction(async (trx) => {
    await user.useTransaction(trx).save()
    await profile.useTransaction(trx).save()
  })

- Pass { client: trx } to model finders so
  reads see the transaction's writes.
- Register post-commit side effects via
  trx.after('commit', cb). A rollback never
  produces orphan side effects.

## Avoid by default
- Firing side effects inline inside the
  callback. Use trx.after('commit', cb).
- Time-consuming work inside a transaction.
  Long transactions hold pool slots and
  row locks.

# Validation

## Recommended Defaults
- Scaffold via node ace make:validator.
  Singular naming, under app/validators/.
- Pre-compile with vine.create({...}).
- Export one named validator per use case,
  createUserValidator, updateUserValidator.
- Fields are required by default. Use
  .optional() to allow undefined,
  .nullable() to require the field but
  allow null.
- Apply request.validateUsing(<validator>)
  in controllers. Body at top level, headers
  under a nested vine.object key.
- Ship VineJS default messages. Customize
  only when explicitly asked.

## Avoid by default
- Synthesizing rule names from training data.
  If a rule is not in the type catalog,
  register a custom rule via the Vine
  extension API.
- Route params and cookies through validators.
  Read via params or request.cookie directly.