create-flowdular 0.2.4 → 0.2.6

package/README.md

@@ -48,6 +48,17 @@ npx create-flowdular@latest my-app
 
 The generator installs dependencies and initializes Git by default. Local development uses PGlite, an embedded PostgreSQL implementation, so the default setup needs no external database server.
 
+## Ready for coding agents
+
+Every app includes `.ai` rules, skills, role prompts, blueprints, policies and
+reference examples, plus `AGENTS.md`, `CLAUDE.md`, `.agents/skills` and
+`.claude/skills`. These files are bundled with the generator and are available
+with `--no-install`. Personal agent settings and credentials are never copied.
+
+Edit `.ai/rules` or `.ai/skills`, then run `pnpm rules:generate`. `pnpm verify`
+checks that the generated instructions are in sync. The instructions explain
+where to find the installed SDK and how to extend the application's modules.
+
 ## Options
 
 Pass generator flags after `--` when using `npm create`:

package/agent-template/.agents/skills/agent-tool-design/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: agent-tool-design
+description: >-
+  Register an API or CLI tool that lets business agents act on a module, with
+  the real harness, permission, idempotency, audit, and test contract.
+---
+# Design and register an agent tool
+
+A module lets agents act on it by registering tools during composition. A tool
+wraps one service operation, takes the tenant from the run context, reuses the
+service validation, bounds its output, and declares the exact permission the
+matching endpoint requires. `parties.core` and `catalog.core` are the reference
+implementations.
+
+This skill designs tools, not business-agent behavior. When a module should
+also ship a ready business agent through `defineAgent()`, read
+`business-agent-design` and register only the exact tools that agent needs.
+
+## 1. The contract in code
+
+- Composition: `PlatformServerContext` (`modules/auth/src/server/composition.ts`) carries `agentTools: PlatformToolRegistry` (`register(tools)`, `list()`; `packages/kernel/src/tool-registry.ts`; a duplicate tool id throws at boot), `settings: ModuleSettingsRuntime`, and `capabilities: PlatformCapabilityRegistry` (`register(id, service)`, `get(id)`, `has(id)`; `packages/kernel/src/capability-registry.ts`). `platform/octane.config.ts` creates the registries, passes them to every module's `createServerComposition`, declares each `settings`, owns each `dispose`, then calls each `start`.
+- Ordering is a non-issue: `agents.core` (`modules/agents/src/platform.ts`) passes `tools: () => context.agentTools.list()` into `createAgentRuntime`, and the harness is built lazily in `start()`, which runs after every module has composed. Tools any module registers during its own compose are therefore visible, whatever the module order.
+- Helpers: import `defineApiAgentTool` from `@flowdular/sdk/harness/tool-adapters` and the types `AgentTool`, `AgentToolContext` from `@flowdular/sdk/harness/runtime`. Both subpaths are free of the Vercel AI SDK; only the harness root (`@flowdular/sdk/harness`) and `@flowdular/sdk/modules/agents/server` pull it. `defineApiAgentTool` returns a frozen `AgentTool { id, transport: 'api', target, description, requiredPermissions, inputSchema?, execute }`. `defineCliAgentTool({ id, capability: { id, risk }, ... })` wraps a CLI capability and throws at definition time for `external` or `destructive` risk.
+- Skills inside `agents.core` are tenant database records behind `agents.skills.*`, appended to agent instructions. They are unrelated to `.ai/skills/**`, which are files for coding agents.
+- A read tool's output can also become a resolvable `{{ variable }}` for variable-aware fields: the tool's `requiredPermissions` is the variable's scope mask. Register a source on `platformVariableRegistry(context.capabilities)`, require an explicit record binding, and invoke the tool with the trusted tenant, actor permission snapshot, and signal. See the `variables` skill for the complete refusal contract.
+- ADR 0002 (`docs/adr/0002-durable-agent-execution.md`): instructions are data, tools are registered by the composition, each tool records an endpoint id or a CLI capability id plus its required permissions, runs are durable with leases.
+
+## 2. Tool shape
+
+```ts
+// src/agent/tools.ts
+import { defineApiAgentTool } from '@flowdular/sdk/harness/tool-adapters';
+import type { AgentTool } from '@flowdular/sdk/harness/runtime';
+import { PARTY_PERMISSIONS } from '../acl/permissions.ts';
+import type { PartyKind } from '../domain/types.ts';
+import type { PartiesRuntime } from '../server/runtime.ts';
+
+const MAX_TOOL_ROWS = 200;
+
+export function partiesAgentTools(
+	runtime: PartiesRuntime,
+): readonly AgentTool[] {
+	return [
+		defineApiAgentTool({
+			id: 'parties.customer.list', // ^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$
+			endpointId: 'parties.records.list', // the read endpoint this wraps
+			description: 'List customers and suppliers of the active tenant.',
+			requiredPermissions: [PARTY_PERMISSIONS.read],
+			inputSchema: {
+				type: 'object',
+				additionalProperties: false,
+				properties: {
+					status: { type: 'string', enum: ['active', 'archived'] },
+					query: { type: 'string', maxLength: 120 },
+				},
+			},
+			execute: async (input, context) => {
+				const value = (input ?? {}) as Record<string, unknown>;
+				const query =
+					typeof value.query === 'string'
+						? value.query.trim().toLocaleLowerCase('en-US')
+						: '';
+				return runtime
+					.service()
+					.list(context.tenantId) // tenant from the run, never from input
+					.filter(
+						(party) =>
+							query === '' ||
+							party.name.toLocaleLowerCase('en-US').includes(query),
+					)
+					.slice(0, MAX_TOOL_ROWS); // bound output
+			},
+		}),
+		defineApiAgentTool({
+			id: 'parties.customer.create',
+			endpointId: 'parties.records.create',
+			description: 'Create a customer or supplier owned by the active tenant.',
+			requiredPermissions: [PARTY_PERMISSIONS.manage],
+			inputSchema: {
+				type: 'object',
+				additionalProperties: false,
+				required: ['name', 'kind'],
+				properties: {
+					name: { type: 'string', maxLength: 160 },
+					kind: { type: 'string', enum: ['customer', 'supplier', 'both'] },
+					vatId: { type: 'string', maxLength: 20 },
+				},
+			},
+			execute: async (input, context) => {
+				const value = (input ?? {}) as Record<string, unknown>;
+				// The service revalidates every field, so a tool cannot persist
+				// what the endpoint would reject.
+				return runtime.service().create(context.tenantId, {
+					name: String(value.name ?? ''),
+					kind: value.kind as PartyKind,
+					vatId: typeof value.vatId === 'string' ? value.vatId : null,
+				});
+			},
+		}),
+	];
+}
+```
+
+```ts
+// src/platform.ts, inside createServerComposition, before the return.
+// register takes readonly unknown[], so no cast is needed.
+context.agentTools.register(partiesAgentTools(runtime));
+```
+
+Export the factory from `src/server/index.ts` so tests and the composition reach it.
+
+Dependencies: `package.json` gets `"@flowdular/sdk/harness": "workspace:*"`. You do not import `@flowdular/sdk/modules/agents` and you do not add `agents.core` to `module.json`: registration flows through the platform-provided registry on the composition context, not an import of agents.core. Adding a scenario bumps `spec/module.yaml` `specVersion` and `module.json` `version` together.
+
+## 3. Execution model you design against (`packages/harness/src/runtime.ts`, `AgentHarness.execute`)
+
+- A tool is offered only when the agent definition lists it in `allowedTools`, the run's explicit `toolGrants` include it, every `requiredPermissions` entry is in the enqueue-time permission ceiling, and the initiating user still holds every permission when the tool is called. The auth runtime reauthorizes the trusted actor and tenant before every call. A stored snapshot never becomes future authority, newly granted scopes do not elevate an old run, and a service actor stays tool-less until its owning module supplies an explicit revocable policy. Otherwise the harness emits `tool.denied` and throws a stable refusal. `assertToolsRegistered` rejects a new run whose agent names an unregistered tool, while an exact idempotent retry returns its already persisted run before consulting mutable definitions or registries.
+- `invokeTool` validates `input` against `inputSchema` first, using a small JSON Schema subset (`type`, `enum`, `required`, `properties`, `additionalProperties: false`, `items`; `packages/harness/src/tool-contract.ts` `validateToolInput`). A violation emits `tool.denied` (reason `TOOL_INPUT_INVALID`) before `execute` runs. The subset does not check string length or format, so the tool enforces those by passing input through the module service.
+- `execute(input, { runId, tenantId, requestedBy, actor, idempotencyKey, permissions, signal })`. Take the tenant from `context.tenantId`. `permissions` is the intersection of the original ceiling and live authorization. `actor` describes the agent run for record history. `additionalProperties: false` already makes the harness refuse a stray `tenantId` field, but never read one anyway.
+- A mutating tool with `idempotency: 'required'` is executable only after the target module implements a durable ledger and the definition declares `idempotencyProtection: 'target-ledger'`. The harness derives a stable key from the durable run id and deterministic tool-call ordinal. The target ledger binds `(tenant, tool id, key)` to a canonical input hash and the first result. A replay returns that result without another mutation; the same key with another tool or input fails closed. Provider tool-call ids are audit metadata only. Never add the declaration before the target migration, repository transaction, and crash-recovery test exist.
+- Each call has a deadline (`tool.timeoutMs`, default 30 s, range 250 to 600000) and the harness caps serialized output at 32 KB (`boundToolOutput`), marking `truncated`. Still page or limit your rows so one call cannot dominate the run window.
+- Events per call land in the run's persisted audit chain: `tool.started`, then `tool.completed` (metadata `tool`, `outputCharacters`, `truncated`) on success, `tool.failed` (reason) on error, or `tool.denied` (reason) when not granted or input-invalid.
+- Runs are enqueued by `POST /api/agent-runs` behind `agents.runs.execute`, claimed by `AgentWorker` with a lease, observed through `GET /api/agent-runs` and the SSE stream. The registered tool ids surface in `GET /api/agents` `tools`, which the Agents form reads to build the allowed-tools grid. Never make a tool block on user input.
+
+## 4. Deliverables for a module
+
+1. Spec: one acceptance scenario per tool group (`PARTIES-AGENT-TOOL`): endpoint wrapped, permission required, validated input, what it refuses (no tenant input; a `manage` tool needs an explicit scenario; bounded output). Bump `specVersion` and `module.json` `version` together.
+2. `src/agent/tools.ts`: every tool calls the module service through the runtime (never a repository, database handle, filesystem or shell), takes `context.tenantId`, and reuses the service validation.
+3. The `register` line in `src/platform.ts`, and the factory exported from `src/server/index.ts`.
+4. For a mutating tool, a numbered migration and target-side idempotency ledger, with the migration mirrored byte for byte in `src/services/migration.ts`. The service commits the business mutation and ledger result in one transaction.
+5. Tests, below, including a replay of the complete harness execution with the same run id and no second business row.
+6. In the Agents screen an agent definition lists the tool id in its allowed tools, the request carries it in `toolGrants`, and the initiating principal still holds the permission. Without all three the tool stays invisible to the model.
+
+## 4b. Worked example
+
+Spec scenario:
+
+```yaml
+acceptanceScenarios:
+  - id: PARTIES-AGENT-TOOL
+    given: An agent run holds parties.records.manage in its permission snapshot and the tool parties.customer.create in its grants.
+    when: The agent invokes the tool with a valid party, and a run without the manage scope invokes the same tool.
+    then: The scoped run creates a tenant-owned party from the run tenant and the harness denies the unscoped run before any write.
+```
+
+Module-local test (`tests/agent-tools.test.ts`) drives `execute` directly. It does
+not assert on `context.permissions`: RBAC is the harness's job, not the tool's.
+
+```ts
+import type { AgentToolContext } from '@flowdular/sdk/harness/runtime';
+import { describe, expect, it } from 'vitest';
+import { partiesAgentTools } from '../src/agent/tools.ts';
+import { createPartiesRuntime } from '../src/server/runtime.ts';
+
+const context = (tenantId: string): AgentToolContext => ({
+	runId: 'run-1',
+	tenantId,
+	requestedBy: 'account-1',
+	permissions: new Set<string>(),
+	signal: new AbortController().signal,
+});
+
+it('creates under the run tenant and ignores a tenant in the input', async () => {
+	const runtime = createPartiesRuntime({ databasePath: ':memory:' });
+	const [, create] = partiesAgentTools(runtime);
+	await create!.execute(
+		{ name: 'Acme', kind: 'customer', tenantId: 'tenant-b' },
+		context('tenant-a'),
+	);
+	expect(runtime.service().list('tenant-a')).toHaveLength(1);
+	expect(runtime.service().list('tenant-b')).toHaveLength(0);
+});
+
+it('reuses the service validation so a tool cannot bypass the endpoint', async () => {
+	const [, create] = partiesAgentTools(
+		createPartiesRuntime({ databasePath: ':memory:' }),
+	);
+	await expect(
+		create!.execute(
+			{ name: 'Acme', kind: 'customer', vatId: 'PL-123' },
+			context('tenant-a'),
+		),
+	).rejects.toMatchObject({ code: 'INVALID_VAT_ID' });
+});
+```
+
+Prove RBAC through the harness (in `modules/agents/tests` with a fake provider,
+where the create tool runs against a `:memory:` repository): a run holding the
+`manage` scope creates the row and emits `tool.started`/`tool.completed`; a run
+whose snapshot lacks it emits `tool.denied` (`TOOL_NOT_GRANTED`) and writes
+nothing.
+
+## 5. Settings a tool may depend on
+
+Declare `settings: defineModuleSettings({...})` (from `@flowdular/sdk/kernel`) by returning it from the composition, keep a reference to `PlatformServerContext.settings` in the tool factory, and read it per call as `settings.get<number>(context.tenantId, '<module>.core', 'key')` at request time, never at boot. Declared settings render in the module's drawer under Administration, Modules automatically.
+
+## Pitfalls
+
+- A tool id equal to an endpoint id is a convention, not a requirement; keep them parallel for traceability. A read-by-id tool with no dedicated endpoint reuses the read endpoint id under the same permission.
+- `requiredPermissions` must be exactly the endpoint's permission; a weaker list lets a run bypass the endpoint's ACL because the tool calls the service directly.
+- Register once per composition; a duplicate id throws in the registry at boot and the platform does not start.
+- Import the helpers from `@flowdular/sdk/harness/tool-adapters` and `@flowdular/sdk/harness/runtime`; never import the harness root or `@flowdular/sdk/modules/agents` from `src/index.ts` or the client, which would pull the Vercel AI SDK into the client bundle.
+- The harness validates only the schema subset; deep validation is the service's job. Pass input through the service so a tool cannot persist what the endpoint would reject.
+- Playground runs use the tenant's readiness-probed provider; the local simulation provider performs no network call and is the only provider in a fresh install.

package/agent-template/.agents/skills/auth-security-review/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: auth-security-review
+description: >-
+  Review a module or platform change for authorization, tenancy, CSRF, input
+  bounds, secrets, and destructive CLI use, with the exact checks and tests the
+  platform relies on.
+---
+# Authentication and security review
+
+## 1. Threat surface of a module endpoint
+
+Check every route in `src/api/endpoints.ts` against `.ai/references/catalog/src/api/endpoints.ts`:
+
+1. `defineEndpoint` (`packages/server/src/endpoint.ts`) with `access: { kind: 'permission', permission }` and `resolveIdentity: endpointIdentityFromContext`. `access: { kind: 'public' }` is allowed only with a written reason (health, sign-in). A raw `new ServerRoute` from `@octanejs/app-core` bypasses all of this; outside `modules/auth` and `packages/server` it is a finding.
+2. Non-GET handlers call `sessionMutationDenial(octane, auth)` before any work. Order inside it (`modules/auth/src/server/session-security.ts`): API token principal (403 `TOKEN_MUTATION_DENIED`), `assertSameOrigin` (`sec-fetch-site`, then `origin`, then `referer`; 403 `CROSS_ORIGIN_REQUEST` or `ORIGIN_REQUIRED`), session cookie (401), `x-csrf-token` compared with `timingSafeEqual` (403 `CSRF_REJECTED`).
+3. Body through `readJsonObject` (415 without `application/json`, 413 above 16 KB) and `requiredString`, `optionalString`, `requiredInteger` with `min` and `max`. A handler that calls `request.json()` itself has no size limit.
+4. Tenant id only from `principalFromContext(octane)!.tenantId`. A `tenantId` read from the body, query or headers is a blocker (`.ai/examples/bad/tenant-from-body`).
+5. Repository: every query on a tenant-owned table has `WHERE tenant_id = ?`; parameters are bound, never interpolated; unique constraints start with `tenant_id`.
+6. Errors return `{ error: { code, message } }` with stable codes and safe messages; no stack, path, or SQL text reaches the client.
+
+## 2. Scope model
+
+`modules/auth/src/acl/scopes.ts`: `AUTH_SCOPES`, `PLATFORM_SCOPES` (`system.workspace.access` gates the shell in `platform/src/App.tsrx`; `system.settings.read` and `system.settings.manage` guard `GET /api/settings` and `POST /api/settings/update` in `modules/auth/src/server/settings-endpoints.ts`), `BUNDLED_MODULE_SCOPES`, `OWNER_SCOPES` (all of them), `MEMBER_SCOPES` (read scopes plus `agents.runs.execute`). Sign-up creates an owner with `OWNER_SCOPES`; member creation copies `OWNER_SCOPES` or `MEMBER_SCOPES` by role (`modules/auth/src/services/auth-service.ts`). A module's scopes reach existing owners through `pnpm flowdular module enable <id> --apply` (which runs the grant) or `pnpm flowdular auth sync-scopes --module <id> --apply` for a re-grant. Navigation in the `Development` group is owner-only in the client (`packages/client/src/shell/navigation.ts`); the server permission stays authoritative.
+
+Review question: does every new scope appear in the spec `permissions`, in `src/acl/permissions.ts`, on the endpoint, and on the client contribution that exposes it?
+
+### Unified audit read surface
+
+Three tenant-scoped trails are readable over HTTP, each a GET behind a read scope with the tenant taken from the principal: `GET /api/auth/audit` (`auth.audit.read`), `GET /api/agent-audit` (`agents.runs.read`), and `GET /api/sandbox/audit` (`sandbox.sessions.read`). They are surfaced together in `auth.core`'s Administration > Audit view, whose source selector is derived from `ModuleClientContext.scopes` so a reader is never offered a source it cannot read. The agent and sandbox trails are hash-chained; `GET /api/agent-audit/verify` and `GET /api/sandbox/audit/verify` (same read scopes) recompute the chain and return `{ verified, brokenAt }` through the same repository walk the `flowdular <module> audit-verify` CLI uses, so CLI and endpoint cannot drift. Reviewing an audit change: the read scope guards both list and verify, the list cursor is `(occurred_at, sequence)` and the sequence is trusted from storage (never from input), and no chain field or metadata may carry a credential, token, or request body.
+
+## 3. API tokens
+
+`Authorization: Bearer clat_...` (`API_TOKEN_PREFIX` in `auth-service.ts`), 256-bit random, stored as SHA-256, scopes intersected with the live membership, max lifetime one year, resolved only when no session cookie is present (`modules/auth/src/middleware/authentication.ts`). Tokens are refused for session-guarded mutations. A module endpoint that should be callable by a token (read for the sandbox bridge) must be a GET behind a permission.
+
+## 4. Secrets
+
+Passwords: scrypt `N=2^17, r=8, p=1`, 64-byte key (`modules/auth/src/services/password.ts`). Sessions: 32 random bytes, CSRF 24 bytes, SHA-256 at rest. Cookies: `HttpOnly; SameSite=Strict; Path=/`, `Secure` and the `__Host-` prefix when `FD_AUTH_SECURE_COOKIE` is true (default in production), 12 hour TTL (`modules/auth/src/server/runtime.ts`). Provider credentials: AES-256-GCM in `modules/agents/src/services/credential-vault.ts`, key from `FD_AGENT_CREDENTIAL_KEY` (required in production). `redactSecrets` in `packages/ai-provider/src/errors.ts` scrubs provider messages; there is no general redacting logger, and a raw driver error can carry the failing statement, so a handler maps it to a Flowdular error code and logs that instead of `console.error(..., error)` with the driver message. A module never logs a principal, a token, or a request body.
+
+## 5. Greps to run
+
+```bash
+grep -rn "new ServerRoute" modules/*/src | grep -v modules/auth          # raw routes outside auth
+grep -rn "tenantId" modules/*/src/api | grep -v principalFromContext      # tenant from input
+grep -rn "request.json()" modules/*/src                                   # unbounded body reads
+grep -rn "console\.\(log\|error\)" modules/*/src                          # logging of principals or bodies
+grep -rn "kind: 'public'" modules/*/src                                   # public endpoints need a reason
+grep -rn "\${" modules/*/src/services/database-repository.ts              # interpolation into SQL
+```
+
+## 6. Destructive and external CLI capabilities
+
+`packages/cli/src/runner.ts`: `external` risk and non-local `destructive` capabilities fail with `APPROVAL_VERIFIER_REQUIRED`; `localOnly` runs only when `FD_ENV` or `NODE_ENV` is `development` or `test` (unset counts as development); `requiresApprovedSpec` needs `--spec` pointing at an approved spec; `destructive` with `--apply` needs `--confirm <token>` equal to the descriptor's `confirmation`. `setup quick` is `auth greenfield` (`--apply --confirm reset-local-auth`) and resets `.flowdular/data/auth.db`. Never point it at `FD_AUTH_DATABASE` of a deployment.
+
+## 7. Required tests per endpoint
+
+Recipe in `modules/auth/tests/endpoints.test.ts`: build the runtime with a `DatabaseAuthRepository` on a `createPgliteTestProvider()` lease, call `route.handler(createContext(new Request(...), {}))`.
+
+- 401 without a cookie or token.
+- 403 with a principal that lacks the permission.
+- Cross-tenant read returns an empty list (service level, on the suite's test provider under the non-bypass `coreloom_runtime` role).
+- Mutation without `x-csrf-token` returns 403 `CSRF_REJECTED`; without `origin` returns 403.
+- Each validation bound returns 400 with its code.
+
+## 7b. Compliance table and report
+
+Fill one row per endpoint before writing findings; a blank cell is a finding.
+
+| Endpoint                        | Permission                   | Identity                      | Tenant source          | Mutation guard                | Body bounds                               | Tests               |
+| ------------------------------- | ---------------------------- | ----------------------------- | ---------------------- | ----------------------------- | ----------------------------------------- | ------------------- |
+| `POST /api/inventory/locations` | `inventory.locations.manage` | `endpointIdentityFromContext` | `principalFromContext` | `sessionMutationDenial` first | `readJsonObject`, `requiredString` max 32 | 401, 403, CSRF, 400 |
+
+Report each finding as: severity (`blocker`, `should-fix`, `taste`), claim, `file:line`, the concrete scenario (who sends what, what happens), the rule (`AGENTS.md` number), the fix. Finish with a verdict: `approved` or `changes-required`. Do not fix code in the review run.
+
+```text
+blocker  Tenant id read from body   modules/inventory/src/api/endpoints.ts:41
+         A member of tenant A posts { tenantId: "B" } and creates a location in B.
+         AGENTS.md 6. Fix: principalFromContext(octane)!.tenantId; drop the field.
+```
+
+## 8. Known platform gaps to keep in mind (not module defects)
+
+The sandbox server (`packages/sandbox/src/server/routes.ts`) has routes without authorization or CSRF, and the session id parameter is joined into paths unvalidated; the sign-in limiter is keyed on email plus `user-agent` (`modules/auth/src/server/endpoints.ts`, `limiterKey`); `users.members.manage` can create an owner because `role` comes from the body (`modules/users/src/api/endpoints.ts`); `emailConfirmation` does not gate sign-in; there are no security headers or a global body limit. A module review does not fix these; name them when a change touches the same area.
+
+## Pitfalls
+
+- `principalFromContext(octane)!` before `resolveIdentity` ran is a null dereference on a public route.
+- A GET that mutates skips `sessionMutationDenial`; mutations are POST or PUT.
+- A `secret: true` setting is write-only through `/api/settings/update`; a module never returns a setting value to the client unless its declaration says `client: true`.
+- Matching a unique violation by message text is the accepted pattern, but the string must include the table name (`<table>.tenant_id`).
+- An `Alert` with the raw server message is fine because the server already returns safe messages; never include the response body of a 500 verbatim.

package/agent-template/.agents/skills/auto-review/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: auto-review
+description: >-
+  Review a finished core or module change against its requirements, public
+  contracts and executable regression evidence before delivery. Report defects
+  with failure scenarios; never approve an unverified change.
+---
+# Auto-review
+
+This is a separate review phase after implementation. Read the owning code, the
+complete change including additions and deletions, its callers, requirements and
+tests. Preserve unrelated edits. Do not load other skills during this phase.
+Do not modify production code, tests, specifications or generated files. Findings
+return to the implementation phase; every later edit requires another review.
+Review is a model assessment, not a guarantee of correctness or spec approval.
+
+## Required checks
+
+For every check, cite the relevant files and concrete evidence. Use a reasoned
+not-applicable explanation only after inspecting the change. Generic "looks good"
+or "tests pass" is not evidence. A missing check blocks a passing verdict.
+
+1. **Correctness:** map each requested behavior and acceptance scenario to code
+   and an observable test. Trace invalid inputs, empty results, boundaries and
+   failure paths. Check existing behavior outside the requested change. Find
+   sibling call sites and copies that need the same fix.
+2. **Security:** trusted principal and tenant identity, explicit permissions,
+   denial tests, CSRF for mutations, input bounds, parameterized SQL, tenant
+   predicates and forced RLS, secret redaction and cross-module authority.
+   Test unauthenticated, denied and cross-tenant requests where applicable.
+3. **Compatibility:** exports, signatures, optional fields, errors, dependency
+   direction and every consumer affected by the contract. Check manifests,
+   declared dependencies, spec/package versions and CLI-generated composition.
+   Applied migrations must remain byte-identical; check new migrations, fresh
+   apply, adoption and tenant isolation through the actual database provider.
+4. **Lifecycle:** concurrency, cancellation, cleanup, bounded memory, resource
+   ownership, durable background work, retries, idempotency and recovery. State
+   the cost of changed loops or queries; investigate new unbounded work.
+5. **Tests:** assertions must observe behavior, not duplicate implementation.
+   A regression test must fail with the defect restored and pass with the fix.
+   Cover relevant negative and failure cases. No skipped assertions, empty
+   suites, mocked-away ownership boundary or weakened existing checks. Record
+   actual commands, results and failures, and distinguish tests not yet run.
+6. **UI:** when rendered behavior changes, inspect the rendered result, keyboard
+   interaction, shared components, translated copy and loading/empty/error/
+   populated/denied states. Record the inspected scenario; otherwise explain
+   why the diff has no rendered effect.
+
+## Core and host module changes
+
+Review only the requested change while accounting for existing workspace edits.
+Run scoped checks first, then `pnpm verify`. For a core change also run `pnpm build`
+(the CLI smoke and platform build exercise integration). Do not waive a failing,
+missing or skipped required check; list unrelated existing failures separately
+and leave verification incomplete. Re-read the final diff after generated output
+or formatting changes. Save a concise report with files reviewed, scenario-to-test
+mapping, commands/results, unresolved findings and remaining risks. Finish with
+pass only when all applicable checks have evidence and no actionable defect
+remains. Root instructions require this phase before declaring the work complete;
+there is no host-side runtime enforcement of a model's review verdict.
+
+## Sandbox
+
+The orchestrator routes a failed `auto-review` gate to this skill. The turn is
+read-only and retains the current role and active module. Inspect the whole module
+change relative to `reference/auto-review-base/`, including deleted files, not
+just your last edit. Preserve the intended next-specialist handoff from the
+implementation turn after a passing review. Use the provided
+reference code and recorded gate output. The orchestrator runs schema, dependency,
+typecheck, tests and format gates; never claim you ran a command it ran later.
+Report verification still pending when needed. Deterministic checks are independent
+of your assessment and must all pass before eject.
+
+Return exactly one fenced `auto-review` JSON object in the closing response,
+followed by the normal handoff line. Each check is a string of 20 to 4000 characters
+with actual evidence or a specific not-applicable explanation. Keep the response
+under 32000 characters. The structure is:
+
+```auto-review
+{
+  "verdict": "fail",
+  "checks": {
+    "correctness": "Files, acceptance scenarios and observed behavior.",
+    "security": "Relevant authorization and tenant denial evidence.",
+    "compatibility": "Public consumers and migration or manifest evidence.",
+    "lifecycle": "Resource ownership and failure-path evidence.",
+    "tests": "Test paths, assertions, actual gate results or pending checks.",
+    "ui": "Rendered inspection evidence or a specific reason not applicable."
+  },
+  "findings": ["Severity; file:line; input/state; wrong outcome; required fix."]
+}
+```
+
+Use `pass` and an empty findings array only when no actionable defect remains.
+Do not copy the example evidence. Include every actionable finding, not taste
+preferences. A failing review returns to implementation; never repair files in
+this turn. A passing record is written by the orchestrator outside the workspace
+and bound to all module file bytes. Subsequent edits invalidate it. Old sessions
+without a current report must run auto-review before eject. Eject rejects skipped
+and missing gates as well as failures; a test suite with no tests fails.
+
+Owning code: `packages/sandbox/src/server/auto-review.ts`, `turns.ts`, `gates.ts`,
+`delivery/steps.ts`, and `packages/coding-agent/src/roles/skills.ts`.

package/agent-template/.agents/skills/bug-hunt/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: bug-hunt
+description: >-
+  Reproduce a defect with the gate runner, map the symptom to the owning layer,
+  fix it there with a failing test first, then hunt its siblings.
+---
+# Hunt a bug
+
+## 1. Reproduce with the tools the gates use
+
+- Server: a vitest case in `tests/module.test.ts` that builds the route and calls it directly. Recipe: `const routes = createXRoutes(auth, runtime); const route = routes.find(...)`, then `await route.handler(createContext(new Request('https://erp.example/api/x', { method: 'POST', headers: { 'content-type': 'application/json', origin: 'https://erp.example', cookie, 'x-csrf-token': csrf }, body }), {}))`. `createContext` comes from `@octanejs/app-core`; a full example with sign-up, cookie and CSRF is `modules/auth/tests/endpoints.test.ts`.
+- Service or repository: `new XService((await createXTestDatabase()).repository)` from the module's `tests/support/database.ts` and await the method.
+- Client logic: move the pure part into a `.ts` helper and test it; `.tsrx` files are outside `tests/**/*.ts`.
+- Run: `pnpm --filter @flowdular/module-<dir> test` (repository root) or ask for the `tests` gate (sandbox). Keep the failing test; it becomes the regression test.
+
+## 2. Symptom to layer
+
+| Symptom                                                                                                    | Where it is decided                                                                                                                                                                                                                                                                             |
+| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 401 `UNAUTHENTICATED`                                                                                      | `packages/server/src/endpoint.ts` (no identity from `resolveIdentity`) or `modules/auth/src/server/session-security.ts` (no session cookie on a mutation)                                                                                                                                       |
+| 403 `FORBIDDEN`                                                                                            | `endpoint.ts`: the permission string is not in the principal's scopes. Check `src/acl/permissions.ts` against the spec and whether `auth sync-scopes` ran                                                                                                                                       |
+| 403 `TOKEN_MUTATION_DENIED`, `CSRF_REJECTED`, `ORIGIN_REJECTED`, `CROSS_ORIGIN_REQUEST`, `ORIGIN_REQUIRED` | `sessionMutationDenial` order: API token, `assertSameOrigin` (`modules/auth/src/api/origin.ts`), cookie session, `x-csrf-token`                                                                                                                                                                 |
+| 415 `CONTENT_TYPE_REQUIRED`, 413 `PAYLOAD_TOO_LARGE`, 400 `INVALID_JSON` or `INVALID_INPUT`                | `packages/server/src/http.ts` `readJsonObject` (16 KB cap) and `requiredString`, `requiredInteger`, `optionalString`                                                                                                                                                                            |
+| 409 on create                                                                                              | the repository maps the unique violation by SQLSTATE `23505` plus the constraint name (`.ai/references/catalog/src/services/database-repository.ts`, `create`); match the code, never the driver message text, and remember that renaming the unique index breaks the constraint check silently |
+| 500 `INTERNAL_ERROR`                                                                                       | the handler threw; `endpoint.ts` logs `[requestId] endpoint <id> failed` with the error                                                                                                                                                                                                         |
+| 404 on a module route                                                                                      | route not mounted: `module.json` `platform.server`, `./platform` export, `src/platform.ts`, `flowdular.json` `modules.enabled`, `platform/src/generated/modules.server.ts` regenerated by `pnpm flowdular module sync --apply`                                                                  |
+| Blank shell or boot error                                                                                  | `packages/client/src/contributions.ts` throws on a duplicate contribution id, a navigation entry whose `viewId` has no view, or an unknown widget slot                                                                                                                                          |
+| Navigation entry missing                                                                                   | scope not granted (`navigationForIdentity` in `packages/client/src/shell/navigation.ts`), or `Development` group for a non-owner                                                                                                                                                                |
+| View falls back to the dashboard                                                                           | `ApplicationShell.tsrx` renders `overview` for a view id that no visible navigation or account menu entry reaches                                                                                                                                                                               |
+| Icon renders as a grid                                                                                     | `glyph` or `Icon name` is not an `ICON_PATHS` key (`packages/ui/src/icons/Icon.tsrx` falls back to `modules`)                                                                                                                                                                                   |
+| Stale data after a change                                                                                  | each component owns a store instance (`useMemo(() => createXClientState(), [])`); check the `store.act` that should have written it. `store.commits(cb)` and `store.stats()` from `segment-state` show what was committed                                                                       |
+| Schema error on start                                                                                      | `runModuleMigrations`: `CHECKSUM_MISMATCH` means applied SQL bytes changed; `PARTIAL_OBJECTS` means only part of a pending migration exists. Never delete or bypass the database to hide either condition; restore the shipped bytes or diagnose the partial schema                             |
+
+## 2b. Reproduction snippets
+
+Service level, no HTTP:
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { CatalogService } from '../src/services/catalog-service.ts';
+import { createCatalogTestDatabase } from './support/database.ts';
+
+it('rejects a sku above 64 characters with a stable code', async () => {
+	const service = new CatalogService(
+		(await createCatalogTestDatabase()).repository,
+	);
+	await expect(
+		service.create('tenant-a', {
+			sku: 'x'.repeat(70),
+			name: 'Too long',
+			kind: 'product',
+			unit: 'each',
+			basePriceMinor: 100,
+			currency: 'EUR',
+		}),
+	).rejects.toThrowError(/between 1 and 64/);
+});
+```
+
+HTTP level, the denial path only needs the route and a bare request:
+
+```ts
+import { createContext } from '@octanejs/app-core';
+
+const [list] = createCatalogRoutes(auth, runtime);
+const response = await list.handler(
+	createContext(new Request('https://erp.example/api/catalog/items'), {}),
+);
+expect(response.status).toBe(401);
+expect(await response.json()).toMatchObject({
+	error: { code: 'UNAUTHENTICATED' },
+});
+```
+
+For a 403 or a mutation you need a principal; the recipe with sign-up, cookie and CSRF is in `test-hardening`.
+
+## 2c. Reading gate output
+
+- `typecheck`: the first error is usually the cause; later ones cascade. `TS2307 Cannot find module` inside a module means an undeclared package or a missing `.ts` extension.
+- `tests`: vitest prints the failing assertion with `Expected` and `Received`; a driver error naming a column type is a value that does not fit the column (`Number.isSafeInteger` at the service boundary), and a comparison that fails on a count or a flag is usually a `BIGINT` returned as a string that skipped the repository's `integer()` helper.
+- `format`: run `pnpm format` (or the sandbox format action); never hand-format.
+- `dependencies`: the message lists the undeclared packages; add them to `package.json` dependencies (the session installs what `package.json` declares and nothing else). A failed `pnpm install` after a `package.json` change is reported under the same gate with the installer output.
+- `module-schema`: `SCHEMA_ADDITIONALPROPERTIES` names a key `module.json` does not know; `MODULE_ENABLED_MISSING` means `flowdular.json` names a module without a manifest; `PLATFORM_SERVER_ENTRY_MISSING`, `PLATFORM_EXPORT_MISSING`, `PLATFORM_CLIENT_ENTRY_MISSING`, `PLATFORM_CLIENT_EXPORT_MISSING` name a composition entry the flags promise but the module lacks; `TRANSLATION_KEYS_MISMATCH` and `TRANSLATION_FILE_MISSING` are locale drift; `SPEC_VERSION_DRIFT` and `LOCALE_NOT_IN_PROJECT` are warnings.
+
+## 3. Fix at the owning layer
+
+Validation belongs to the HTTP helpers and the service, not to the client. Tenant scoping belongs to the repository query and the endpoint's `principalFromContext`. Presentation belongs to the view. A fix that adds a second check in a different layer hides the defect; move it instead.
+
+Smallest change: write the failing test, make it pass, run `pnpm --filter @flowdular/module-<dir> typecheck` and `test`, and `pnpm format` when the format gate complains (the sandbox has a format action for that).
+
+## 4. Hunt siblings
+
+The bundled modules share one shape. After fixing `modules/<dir>`, grep the same pattern in `.ai/references/catalog`, `modules/users`, `modules/profile`, `modules/agents`, `modules/sandbox`: `grep -rn '<pattern>' modules/*/src`. Report siblings you did not fix.
+
+## 5. Reporting
+
+State the root cause (input and state to wrong outcome), the file and line, the regression test name, and the siblings. Do not claim a fix without the test passing where it failed before.
+
+## Pitfalls
+
+- The sandbox `tests` gate passes with zero tests; a green gate is not evidence.
+- A test never points at a running deployment; it takes its database from `createPgliteTestProvider()` through the module's `tests/support/database.ts`, which runs PostgreSQL inside the test process.
+- `principalFromContext(octane)!` is only safe after `resolveIdentity`; a public endpoint has no principal.
+- Do not add `try/catch` that swallows the error to make a 500 disappear; map it to a stable code or let it surface.