@event4u/agent-config 2.10.0 → 2.12.0

package/.agent-src/skills/nextjs-patterns/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: nextjs-patterns
+description: "Writes Next.js App Router code — Server Components, Server Actions, RSC boundaries, route handlers, caching, and streaming — matching framework conventions and project architecture."
+source: package
+domain: engineering
+---
+
+# nextjs-patterns
+
+## Compatibility
+
+- **Tested against:** Next.js `14.x` and `15.x` (App Router), React `18+` / `19+`.
+- Pages Router is **out of scope**. On a Pages-Router project (no `app/`),
+  fall back to plain React skills; ask before introducing App Router.
+
+## When to use
+
+Use this skill for Next.js-specific code generation and editing on the App Router:
+
+- Server Components (RSC) and Client Components (`"use client"`)
+- Server Actions (`"use server"`)
+- Route Handlers (`app/api/**/route.ts`)
+- Layouts, templates, loading / error / not-found boundaries
+- Data fetching with `fetch` + cache directives
+- `revalidatePath` / `revalidateTag` invalidation
+- Streaming and `<Suspense>` boundaries
+- Middleware (`middleware.ts`)
+- Metadata API (static + dynamic)
+- Route Groups, Parallel Routes, Intercepting Routes
+
+## When to use the analysis sibling
+
+When the task is **understanding** how a Next.js app boots, where the
+server/client boundary lives, what is cached vs streamed, or why a
+hydration mismatch fires — defer to `project-analysis-nextjs` first,
+then return here for the edit.
+
+## Procedure: write Next.js code
+
+1. **Confirm App Router** — `app/` directory exists; `next.config.{js,ts,mjs}` present.
+2. **Confirm version** — `package.json` major for `next`. 14.x vs 15.x differs in
+   default caching (15.x is uncached by default for `fetch`) and in `cookies()` /
+   `headers()` being async.
+3. **Inspect routing layout** — flat `app/` vs grouped (`app/(marketing)/`,
+   `app/(app)/`); identify shared layouts and parallel routes.
+4. **Inspect data layer** — Server Actions vs route handlers vs external API;
+   ORM (Prisma, Drizzle) or fetch-based.
+5. **Inspect styling** — Tailwind, CSS Modules, or styled engine; respect the
+   chosen stack, do not mix.
+6. **Check test conventions** — Vitest / Jest + RTL for components; Playwright
+   for E2E; route-handler tests via `node` runtime.
+
+## Server vs Client boundary
+
+- **Server Components are the default.** Add `"use client"` only when a leaf
+  component needs state, effects, browser APIs, or event handlers.
+- The `"use client"` boundary is **viral upward at the import graph**, but you
+  can keep a Server Component **rendered as a child** of a Client Component
+  by passing it as a prop / `children` — that pattern keeps server logic out
+  of the client bundle.
+- Never put database access, secrets, or server-only modules inside a Client
+  Component or a file imported by one. Use `import "server-only"` at the top
+  of a server module to make leaks fail at build time.
+- Symmetric guard: `import "client-only"` for code that must never run on the
+  server (e.g. browser-only SDKs).
+- Props passed from Server → Client must be serializable. No functions, no
+  Dates with custom prototypes, no `Map` / `Set` — use plain JSON.
+
+## Server Actions
+
+- Declare with `"use server"` at the top of the file or per-function.
+- Server Actions are **server-only RPC**; never call them from `useEffect` for
+  pure data fetching — that is what Server Components are for.
+- Always **validate input** (zod or equivalent) at the entry of the action —
+  the caller is the client; treat it as hostile.
+- Always **re-authorize** inside the action; do not trust client-side guards.
+- After a mutation: call `revalidatePath()` / `revalidateTag()` or `redirect()`.
+- Return shape: a `{ ok: true, data }` / `{ ok: false, error }` discriminated
+  union — never throw across the action boundary for expected errors.
+- Use `useActionState` (15.x) / `useFormState` (14.x) on the client for
+  progressive enhancement; the form must work without JS.
+
+## Route Handlers
+
+- `app/api/**/route.ts` exports `GET`, `POST`, etc.
+- Handlers run on the **node runtime by default**; opt into `edge` only when
+  the dependency set supports it.
+- Read request body once: `await req.json()` or `await req.formData()`.
+- Return `Response` / `NextResponse`. Use `NextResponse.json` for JSON +
+  consistent status codes.
+- Authentication and rate limiting happen **inside** the handler or via
+  `middleware.ts`; do not assume any framework default.
+- Cache behavior: route handlers are dynamic by default in 15.x. Add
+  `export const dynamic = 'force-static'` / `revalidate = N` explicitly.
+
+## Caching and revalidation (14.x vs 15.x)
+
+- **14.x**: `fetch` is cached by default (force-cache); opt out with
+  `{ cache: 'no-store' }` or segment-level `export const dynamic = 'force-dynamic'`.
+- **15.x**: `fetch` is **not cached by default**; opt in with
+  `{ cache: 'force-cache' }` or `{ next: { revalidate: N } }`.
+- Use **tag-based revalidation** for shared invalidation surface:
+  `fetch(url, { next: { tags: ['posts'] } })` then `revalidateTag('posts')`.
+- Use `revalidatePath('/blog/[slug]', 'page')` for targeted page invalidation.
+- Never call `revalidate*` from a Client Component — wrap it in a Server Action.
+- `unstable_cache` / `cache` (React) wrap pure server functions for memoization
+  within a request; respect the difference between request-scoped and
+  cross-request caching.
+
+## Data fetching patterns
+
+- Prefer fetching in **the Server Component that uses the data**, not in a
+  layout, to allow per-route streaming.
+- Parallel fetching: declare independent promises and `await` together —
+  avoid sequential `await` chains that block streaming.
+- `<Suspense>` boundaries make slow data non-blocking; wrap each independent
+  data dependency in its own Suspense, not the whole page.
+- `loading.tsx` is a default Suspense fallback for the segment; do not use it
+  as a global spinner.
+- Avoid `useEffect` for initial data load in Client Components — fetch on the
+  server and pass props.
+
+## Layouts, templates, error and not-found
+
+- `layout.tsx` is a **persistent** wrapper across navigations; do not put
+  per-page logic there.
+- `template.tsx` re-renders on every navigation; use only when a layout
+  cannot.
+- `loading.tsx`, `error.tsx`, `not-found.tsx` are **per-segment**; nest them
+  to localize fallbacks.
+- `error.tsx` must be a Client Component (`"use client"`); accept `error` and
+  `reset` props.
+
+## Middleware
+
+- `middleware.ts` at the project root runs on the **edge runtime** before a
+  request hits a route — use for auth redirects, locale negotiation, A/B.
+- No database access from middleware; the edge runtime cannot run most node
+  drivers. Use a session cookie + lightweight verification.
+- `matcher` config narrows which paths invoke it — never let middleware run
+  on every asset.
+
+## Metadata, performance, env
+
+- Metadata: static `export const metadata`; dynamic `generateMetadata()`.
+  `generateStaticParams` for static dynamic-segment generation.
+- `next/image`, `next/font`, `next/dynamic` for images, fonts, code-split
+  Client Components — never bare `<img>`, CSS `@import` Google Fonts, or
+  unguarded heavy imports.
+- A single `"use client"` near the top of a tree pulls the subtree into the
+  client bundle — keep the boundary at the leaf.
+- Env: server-only `DATABASE_URL` etc.; client-exposed must be prefixed
+  `NEXT_PUBLIC_*` and is NOT secret. Validate env at boot (zod) and import
+  the validated object — never `process.env` ad hoc.
+
+## Output format
+
+1. Next.js code following App Router conventions and the project's existing layout.
+2. All related files (page, layout, server action, route handler, schema, test) as needed.
+3. When a cache surface changes — point at the invalidation call (`revalidateTag` / `revalidatePath`).
+
+## Do NOT
+
+- Do NOT add `"use client"` to a file that does not need it — it pulls the
+  subtree into the client bundle.
+- Do NOT import server modules (db client, secrets) from a Client Component
+  file — even transitively. Guard with `import "server-only"`.
+- Do NOT call Server Actions from `useEffect` to fetch data — fetch on the server.
+- Do NOT throw across a Server Action boundary for expected errors — return a
+  result union.
+- Do NOT trust client-side authorization in a Server Action or route handler —
+  re-check.
+- Do NOT mutate without revalidating — stale UI is a class of bug, not a design.
+- Do NOT mix Pages Router and App Router patterns in one feature — pick one.
+- Do NOT assume 14.x caching defaults on 15.x; verify the major before reasoning about cache.
+
+## Gotcha
+
+- **15.x async APIs**: `cookies()`, `headers()`, `params`, `searchParams` are
+  **async** in 15.x. Code that ran on 14.x will silently misbehave (Promise
+  rendered as an object) until awaited.
+- **Hydration mismatch**: rendering `Date.now()`, `Math.random()`, or
+  locale-dependent strings without `suppressHydrationWarning` or a Client
+  boundary causes a hydration error.
+- **`"use client"` is not opt-in for hooks**: it is required for any file
+  using `useState`, `useEffect`, `useRef`, or browser globals.
+- **Server Actions and forms**: a Server Action used as a form action must
+  accept `FormData`. Mixing `FormData` and typed args breaks progressive
+  enhancement.
+- **Cache lies during dev**: dev mode ignores most cache directives. Verify
+  caching behavior in a production build (`next build && next start`).
+- **`revalidatePath` requires the route group syntax** for parallel/dynamic
+  segments — bare paths silently miss.
+- **Edge runtime ≠ Node**: most npm packages with native deps or Node-only
+  APIs (`fs`, `crypto.createHash`) fail at the edge. Pin runtime per route.
+
+## Auto-trigger keywords
+
+- Next.js / App Router · Server Component (RSC) · Client Component (`"use client"`)
+- Server Action (`"use server"`) · Route Handler (`app/api`) · `middleware.ts`
+- `revalidatePath` / `revalidateTag` / `unstable_cache`
+- `next/image` / `next/font` / `next/dynamic`
+- `layout.tsx` / `loading.tsx` / `error.tsx` / `not-found.tsx`

package/.agent-src/skills/skill-writing/SKILL.md

@@ -3,6 +3,7 @@ name: skill-writing
 description: "Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'."
 source: project
 domain: process
+meta_skill: true
 ---
 
 # skill-writing
@@ -62,22 +63,25 @@ Ask: **"Does the model need this to do its job correctly?"**
 
 ### Skills and commands share the `.claude/skills/` namespace
 
-Skills (`.agent-src.uncompressed/skills/{name}/SKILL.md`) AND commands
-(`.agent-src.uncompressed/commands/{name}.md`) both project into
-`.claude/skills/` (`scripts/compress.py` → `generate_claude_skills` +
-`generate_claude_commands`). Claude treats the directory as native
-skills.
-
-* Same-name collision: skill wins, command is skipped
-  (`generate_claude_commands` honors this). Don't reuse a command's
-  slug for a skill unless the command should retire.
-* Both compete on `description` for routing. A weak skill description
-  is shadowed by a stronger same-domain command — and vice versa.
-  Trigger phrasing must be precise (§ 1b below).
-* Workflow has both "user types `/foo`" path AND "model picks this up
-  from intent" path → author the skill first, let the command delegate
-  via `skills:` frontmatter. Two artifacts with the same trigger
-  surface fight each other in the router.
+Skills in `.agent-src.uncompressed/skills/{name}/SKILL.md` AND commands in
+`.agent-src.uncompressed/commands/{name}.md` both project into
+`.claude/skills/` (see `scripts/compress.py` →
+`generate_claude_skills` + `generate_claude_commands`). Claude treats
+the whole directory as native skills.
+
+Implications for skill authors:
+
+* If a same-name command already exists, the skill takes priority and
+  the command is skipped (`generate_claude_commands` honors this).
+  Don't reuse a command's slug for a skill unless the command should
+  retire.
+* Both artifacts compete on `description` for routing. A weak skill
+  description is shadowed by a stronger same-domain command — and vice
+  versa. Make trigger phrasing precise (§ 1b below).
+* When the workflow has both a "user types `/foo`" path AND a "model
+  picks this up from intent" path, author the skill first and let the
+  command delegate (`skills:` frontmatter). Two artifacts with the same
+  trigger surface fight each other in the router.
 
 ### When "Nothing" is the right answer
 
@@ -263,6 +267,87 @@ Example:
 * K7: Created with analysis (not blind, expected behavior defined)
 * Size: Within limits (see size-and-scope guideline)
 
+### 7. Run + iterate evals (quantitative loop)
+
+Triggers (`evals/triggers.json`) check **routing**. A separate
+`evals/evals.json` checks **behavior** — does the skill make the agent
+produce a better answer than baseline? Add this layer for any skill
+where the procedure has measurable output (commands, artifacts,
+structured text). Skip for evergreen heuristics with no falsifiable
+output (e.g. `direct-answers`, `language-and-tone`) unless the user
+asks for it.
+
+**Workspace layout** (all under `.gitignore`):
+
+```
+.agent-src.uncompressed/skills/{name}/evals/
+  triggers.json              # tracked — routing eval (§ 1c)
+  evals.json                 # tracked — behavior eval definitions
+  runs/                      # gitignored — per-iteration outputs
+    {timestamp}-baseline/    # sub-agent run without the skill
+    {timestamp}-with-skill/  # sub-agent run with the skill
+    {timestamp}-benchmark.json
+```
+
+**`evals.json` shape** — 3–10 scenarios, each with prompt + grading
+rubric:
+
+```json
+{
+  "skill": "{name}",
+  "scenarios": [
+    {
+      "id": "happy-path",
+      "prompt": "<full user-shaped task that exercises the skill>",
+      "assertions": [
+        {"kind": "contains", "value": "<expected substring in output>"},
+        {"kind": "file_exists", "path": "<artifact path the skill should create>"},
+        {"kind": "rubric", "criterion": "<one-line judgement, e.g. 'output includes a numbered procedure'>"}
+      ]
+    }
+  ]
+}
+```
+
+`contains` / `file_exists` grade deterministically. `rubric` items grade
+via a fresh sub-agent reading the output against the criterion — keep
+each criterion to one falsifiable sentence.
+
+**Loop** (orchestrated by `scripts/run_skill_evals.py`):
+
+1. **Scaffold** — `python3 scripts/run_skill_evals.py scaffold {skill}`
+   creates `runs/{timestamp}-{baseline,with-skill}/` and seeds each
+   scenario's `meta.json`.
+2. **Baseline run** — spawn one sub-agent per scenario **without** the
+   skill loaded. Capture stdout + any artifacts into
+   `runs/{timestamp}-baseline/{scenario-id}/`.
+3. **With-skill run** — same scenarios, same sub-agent harness, **with**
+   the skill loaded. Capture into `runs/{timestamp}-with-skill/{scenario-id}/`.
+4. **Grade** — for each scenario, write a `grade.json` file with
+   per-assertion pass/fail. Deterministic assertions auto-grade;
+   rubric assertions need a grader sub-agent.
+5. **Aggregate** — `python3 scripts/run_skill_evals.py aggregate {skill}
+   --run {timestamp}` produces `runs/{timestamp}-benchmark.json` with
+   pass-rate, timing, token deltas baseline-vs-with-skill.
+6. **Report** — `python3 scripts/run_skill_evals.py report {skill}
+   --run {timestamp}` prints the diff. Iterate on the skill body
+   until `with-skill` outperforms `baseline` on every scenario.
+
+The script ships with sub-agent spawning **stubbed** — the orchestration
+layer is per-environment (Claude Code, Augment, council). Implement
+the spawn function once for your environment, the rest of the loop
+(aggregate / report / scaffold) works out of the box.
+
+**Exit criterion** — every scenario passes with-skill, at least one
+fails baseline (proves the skill earns its slot). Commit the
+`evals.json` alongside the skill; never commit `runs/`.
+
+Neighbors:
+* `description-assist` — iterate on the trigger phrasing
+* `skill-reviewer` — structural 7-Killers audit
+* `lint-skills` — static checks (frontmatter, sections, size)
+* `skill-improvement-pipeline` — production-learning capture
+
 ## Output format
 
 1. Complete SKILL.md file

package/.agent-src/skills/sql-writing/SKILL.md

@@ -17,7 +17,7 @@ Do NOT use when:
 
 ## Procedure: Write raw SQL
 
-1. **Choose approach** — Use query builder when possible. Raw SQL only when query builder can't express the query.
+1. **Inspect call site & choose approach** — identify every dynamic value flowing into the query, then pick: query builder when possible. Raw SQL only when query builder can't express the query.
 2. **Parameterize** — Every variable must use `?` binding or named `:param`. Never interpolate PHP variables into SQL strings.
 3. **Use MariaDB syntax** — Not PostgreSQL or MSSQL. Check `php/sql.md` for MariaDB-specific patterns.
 4. **Verify** — Run EXPLAIN on complex queries. Check that no PHP interpolation (`"$var"`, `'{$var}'`) appears in SQL.

package/.agent-src/skills/symfony-workflow/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: symfony-workflow
+description: "Writes Symfony code following framework conventions, container wiring, and modern best practices for controllers, services, bundles, Messenger, Doctrine, security, and console commands."
+source: package
+domain: engineering
+---
+
+# symfony-workflow
+
+## When to use
+
+Use this skill for all Symfony-specific code generation and editing tasks, especially when working with:
+
+- Controllers (annotated / attribute-routed)
+- Request listeners / event subscribers
+- Services and Dependency Injection (`services.yaml`)
+- Forms and validators
+- Doctrine entities, repositories, and migrations
+- Security: firewalls, voters, authenticators
+- Messenger handlers and transports
+- Console commands
+- Bundles, compiler passes, and tagged services
+- Twig templates and view logic
+
+This skill extends the base `php-coder` skill and applies Symfony conventions on top of the project's general PHP rules.
+
+## When to use the analysis sibling
+
+When the task is **understanding** how a Symfony app boots, wires its container, routes requests, or fails at runtime — defer to `project-analysis-symfony` first, then return here for the edit. This skill assumes the kernel/container layout is already known.
+
+## Procedure: write Symfony code
+
+→ **First apply the `php-coder` skill** for general PHP rules.
+
+Then add these **Symfony-specific** checks:
+
+1. **Confirm Symfony** — `bin/console` exists, `composer.json` lists `symfony/framework-bundle`.
+2. **Confirm version** — `composer.lock` for the framework-bundle major. 5.x → 6.x → 7.x differs in attribute routing, voter signatures, and Messenger DSN shape.
+3. **Inspect app structure** — standard, modular (`src/Module/<Name>/`), or DDD-style. Do not enforce a layout the project does not use.
+4. **Check config layout** — `config/packages/<env>/`, `services.yaml` autowiring vs explicit bindings, `config/bundles.php`.
+5. **Check test conventions** — PHPUnit/Codeception; unit vs integration vs functional split.
+
+## Core Symfony principles
+
+- Follow Symfony conventions unless the project explicitly does otherwise.
+- Keep controllers thin — delegate to services.
+- Rely on autowiring + autoconfigure unless the project has explicit bindings.
+- Prefer attributes over annotations on 6.x+; keep annotations only if the codebase still uses them.
+- Use service IDs by FQCN — `App\Service\Foo`, not custom string IDs.
+- Services are private by default; do not flip `public: true` to make tests pass.
+- Do not bypass the container with `new` on classes that have collaborators.
+
+## HTTP layer rules
+
+- Controllers:
+    - extend `AbstractController` only when the project does
+    - accept `Request` or a DTO; delegate business logic; return a `Response` variant
+- Use `#[Route]` attributes on 6.x+; YAML routes only where the project already does.
+- Use `#[MapRequestPayload]` / `#[MapQueryString]` (7.x+) for request DTOs when the project uses them.
+- Validate via Symfony Validator on the DTO, not inline in the controller.
+- Use `ParamConverter` / argument resolvers for entities only when the project uses them.
+
+## Validation rules
+
+- Symfony Validator with constraints on DTOs / entities.
+- Prefer attribute constraints (`#[Assert\NotBlank]`, `#[Assert\Email]`) on 6.x+.
+- Render errors from `ConstraintViolationListInterface` — never compose error arrays by hand.
+- Validation is declarative; do not put domain validation in entity setters.
+
+## Service layer and DI rules
+
+- One responsibility per service; constructor injection.
+- Interfaces when there are multiple implementations or the boundary is mocked.
+- Tagged services for collecting implementations — `#[AutoconfigureTag]` or YAML tags, never an injected array of FQCNs.
+- Decorators via `#[AsDecorator]` (6.1+); respect priority.
+- Compiler passes only when wiring cannot be expressed via attributes/YAML.
+- Do not call `Container::get` in application code.
+
+## Routing rules
+
+- Follow the existing organization — attributes on controllers, or YAML in `config/routes/`.
+- Route names: `<resource>_<action>` (`user_show`, `invoice_list`).
+- `#[IsGranted]`, `#[RateLimit]` at the route level, not inside the controller body.
+- `requirements:` for path parameter constraints; do not validate in the controller.
+
+## Response rules
+
+- Match the project's response style: Twig, `JsonResponse`, API Platform, or redirects with flash.
+- For APIs: consistent status codes; `ConstraintViolationList` → `application/problem+json`; DTOs / serializer groups, not raw entities.
+- Do not return entities directly unless the project consistently does that.
+
+## Messenger and async work
+
+- Messenger for async/deferred work; one message class per intent.
+- Handlers: `MessageHandlerInterface` (5.x) or `#[AsMessageHandler]` (6.x+).
+- Route via `framework.messenger.routing` in `config/packages/messenger.yaml`.
+- Configure `failure_transport` explicitly — without it, failed messages disappear.
+- Pass IDs, not entities; the consumer re-fetches.
+
+## Events and subscribers
+
+- `#[AsEventListener]` (6.1+) or `EventSubscriberInterface` — match the project's convention.
+- Past-tense event names (`UserRegistered`, `OrderPaid`); one side-effect per subscriber.
+- Respect priority on `kernel.request` / `kernel.response` — wrong priority is a frequent bug source.
+
+## Security, voters, authorization
+
+- One firewall per surface in `config/packages/security.yaml` (main, API, admin).
+- Voters for object-level permissions; never role checks in templates or controllers.
+- `#[IsGranted]` on actions; `$this->isGranted()` only when the result drives downstream logic.
+- Stateless APIs: token-based authenticator, not form-login.
+
+## Config and environment
+
+- Read via `ParameterBagInterface` or `#[Autowire(param: ...)]` — never `$_ENV` directly.
+- New env vars in `.env` (+ `.env.test`); production values in deployment config.
+- Bundle config under `config/packages/<bundle>.yaml`; env overrides under `config/packages/<env>/`.
+
+## Doctrine and persistence
+
+- Doctrine ORM unless the project uses DBAL/raw SQL by convention.
+- Repositories for non-trivial queries; no inline QueryBuilder in controllers/services.
+- N+1 awareness: fetch joins via `addSelect` or `EAGER` when always needed.
+- Transactions via `EntityManager::wrapInTransaction()` for multi-write atomicity.
+- Lifecycle hooks (`PreFlush`, `PostUpdate`) — no domain logic there unless the project already does.
+
+## Migrations
+
+- Generate via `doctrine:migrations:diff`; review before commit.
+- Reversible — implement `up()` and `down()`.
+- One concern per migration; destructive prod changes split into expand → migrate → contract.
+
+## Twig
+
+- Templates are dumb — presentation only; pre-computed view models from the controller/service.
+- Reuse via `{% extends %}` / `{% include %}` / macros.
+- Auto-escape on; `|raw` only when content is provably safe.
+
+## Bundles and compiler passes
+
+- Bundles are for reusable, redistributable code — not "another folder".
+- Compiler passes only when wiring cannot be expressed via attributes/YAML.
+
+## Console commands
+
+- `#[AsCommand]` (6.x+); one command class per intent; constructor injection.
+- Long-running: `--limit`, `--time-limit`, graceful `SIGTERM` shutdown.
+- Output via `OutputInterface` — never `echo`.
+
+## Output format
+
+1. Symfony code following framework conventions and project architecture.
+2. All related files (controller, service, DTO, repository, test, config) as needed.
+3. Schema changes — migration file plus updated entity/mapping.
+
+## Do NOT
+
+- Business logic in controllers, entities, listeners, or Twig.
+- Bypass the container with `new` on classes with collaborators.
+- `$_ENV` / `$_SERVER` direct access — go through the parameter bag.
+- Return Doctrine entities from an API endpoint — use DTOs or serializer groups.
+- Silently swallow Messenger failures — route to a failure transport.
+- Flip services `public: true` to make tests pass — use the test container.
+- Pass entities through Messenger — pass IDs.
+- Mix attribute and YAML routing for the same controller surface.
+
+## Gotcha
+
+- Autowiring fails silently when two implementations exist without explicit binding — read the error, don't just flip `public: true`.
+- `#[IsGranted]` is a no-op if the controller is not a service (autoconfigure handles it by default).
+- Messenger `failure_transport` is opt-in; without it, failures vanish.
+- Compiled container changes need `cache:clear` in `prod` before debugging "config not applied".
+- Symfony 7.x removed deprecated APIs — verify `composer.lock` before assuming 6.x patterns work.

package/.agent-src/templates/scripts/work_engine/hook_bootstrap.py

@@ -23,6 +23,7 @@ from .hooks.builtin import (
     MemoryVisibilityHook,
     StateShapeValidationHook,
     TraceHook,
+    build_decision_gate_hook,
 )
 from .hooks.settings import HookSettings, load_hook_settings
 
@@ -58,6 +59,9 @@ def _build_hook_registry(args: argparse.Namespace) -> HookRegistry:
         DirectiveSetGuardHook().register(registry)
     if settings.decision_trace:
         DecisionTraceHook().register(registry)
+    gate_hook = build_decision_gate_hook(settings.decision_engine)
+    if gate_hook is not None:
+        gate_hook.register(registry)
     if settings.memory_visibility:
         MemoryVisibilityHook(
             cost_profile=settings.cost_profile,

package/.agent-src/templates/scripts/work_engine/hooks/builtin/__init__.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 from .chat_history_append import ChatHistoryAppendHook
 from .chat_history_halt_append import ChatHistoryHaltAppendHook
+from .decision_gate import DecisionGateHook, build_decision_gate_hook
 from .decision_trace import DecisionTraceHook
 from .directive_set_guard import DirectiveSetGuardHook
 from .halt_surface_audit import HaltSurfaceAuditHook
@@ -23,10 +24,12 @@ from .trace import TraceHook
 __all__ = [
     "ChatHistoryAppendHook",
     "ChatHistoryHaltAppendHook",
+    "DecisionGateHook",
     "DecisionTraceHook",
     "DirectiveSetGuardHook",
     "HaltSurfaceAuditHook",
     "MemoryVisibilityHook",
     "StateShapeValidationHook",
     "TraceHook",
+    "build_decision_gate_hook",
 ]