@jaimevalasek/aioson 1.33.1 → 1.37.0

package/template/.aioson/docs/play/llm-data-and-bindings.md

@@ -29,14 +29,56 @@ Play manages global LLM connections in Settings:
 
 Apps should not store Play LLM secrets in repository files or frontend code.
 
+Env vars Play injects at spawn (one per configured connection, since 2026-07-02):
+
+| Play LLM connection | Injected env var |
+|---|---|
+| OpenAI | `OPENAI_API_KEY` |
+| Claude (Anthropic) | `ANTHROPIC_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+| Google Gemini | `GEMINI_API_KEY` |
+| DeepSeek | `DEEPSEEK_API_KEY` |
+| xAI | `XAI_API_KEY` |
+
+Alongside the keys, Play injects **`AIOSON_LLM_CHAIN`** (since 2026-07-02): a
+JSON string WITHOUT keys carrying the validated model per operation and the
+fallback order the user arranged in Play Settings:
+
+```json
+{
+  "exportedAt": "2026-07-02T18:00:00.000Z",
+  "appScope": null,
+  "configs": [
+    {
+      "provider": "openrouter",
+      "operation": "text_generation",
+      "model": "deepseek/deepseek-chat",
+      "baseUrl": "https://openrouter.ai/api/v1",
+      "priority": 1
+    }
+  ]
+}
+```
+
 Expected app behavior:
 
 - Prefer app-local explicit config only when the app intentionally lets the user override provider settings.
-- Otherwise read provider API keys injected by Play during spawn, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENROUTER_API_KEY`.
+- Otherwise read the provider API keys injected by Play during spawn (table above).
+- **Do not hardcode models.** For each operation the app needs (`text_generation`, `image_understanding`, `speech_to_text`, ...), pick the first `configs[]` entry for that operation (sorted by `priority`) whose provider has its `*_API_KEY` present, and use that entry's `model` and `baseUrl`. Fall back to app defaults only when `AIOSON_LLM_CHAIN` is absent or has no entry for the operation.
+- Gemini, DeepSeek and xAI are OpenAI-compatible — reuse an OpenAI-compatible client pointed at the entry's `baseUrl`.
 - Lazy-initialize LLM clients. Do not instantiate SDK clients at module load, because missing keys can crash the backend before the app can render a degraded state.
-- Treat `llm-chain.json` as metadata/order only when present. It must not contain API keys.
+- Treat `AIOSON_LLM_CHAIN` as metadata/order only. It never contains API keys.
 - Treat `aioson-models.json` or `llm-chain.json` in the app cwd as optional/legacy for installed apps, not the primary credential contract.
 
+Injection lifecycle — env vars only exist at spawn time:
+
+- Play injects on UI-driven spawn of an installed app AND on draft preview (`spawn_draft`), so an app under development tests with the same contract it will have once installed.
+- Supervisor auto-respawn preserves the keys from the original spawn.
+- A process that is already running does NOT pick up a key configured afterwards. After adding or changing a Play LLM connection, stop and reopen the app (or the draft preview).
+- A backend started by hand outside Play (`npm run dev` in a terminal or agent session) receives nothing — set the key in that shell env or use app-local config for that scenario.
+
+Troubleshooting "provider not configured" in the app UI while the Play connection exists: (1) the app process started before the key was configured — close and reopen the app; (2) the backend is running outside Play; (3) the app expects a provider the user did not configure — Play injects only the keys that exist, one env var per provider.
+
 Recommended lazy pattern:
 
 ```ts
@@ -178,7 +220,9 @@ await fetch(`${PLAY_BASE}/api/bindings/${APP_SLUG}`, {
 
 ## Executing connectors
 
-After binding, execute through ProductBridge by alias:
+After binding, execute through ProductBridge by alias. The SAME endpoint runs
+all three connector types (`mcpi`, `api`, `mcp`) — Play routes by the
+connector's type (since 2026-07-02):
 
 ```http
 POST http://localhost:5180/api/mcp/execute
@@ -188,14 +232,33 @@ Content-Type: application/json
   "alias": "busca-produtos",
   "params": {
     "search": "dipirona"
-  }
+  },
+  "tool": "tool-name"
 }
 ```
 
-The alias must match both:
+`tool` is optional and only used for `mcp` connectors that expose more than
+one tool (a server with exactly one tool needs no `tool` field).
+
+Response shape is the same for all types:
+`{ "data": <json>, "error": null | "message", "duration_ms": <n> }`.
+
+What each type does:
+
+- `mcpi` — runs the query template on the TARGET database of the Play
+  Database Connection (credentials from Play's keyring), `{{param}}` becomes a
+  prepared-statement bind. Drivers: postgresql, mysql, sqlite.
+- `api` — HTTP request to the connector URL: `{{param}}` interpolated into the
+  URL (percent-encoded); leftover params become query string (GET/DELETE) or a
+  JSON body (POST/PUT); auth headers from Play's keyring are applied.
+- `mcp` — LOCAL stdio MCP server: Play spawns the connector command, performs
+  the JSON-RPC handshake (initialize → tools/list → tools/call) and returns
+  the tool result. Spawn per call, 60s timeout.
 
-- `data_bindings[].id`
-- the active binding alias
+MCP scope today: local stdio servers only (auth via the command's own
+env/args — no OAuth involved). REMOTE MCP servers over HTTP, which use OAuth
+2.1 per the MCP spec, are NOT supported yet — do not fake them with manual
+headers; treat that binding as unavailable and degrade.
 
 ## Degraded state
 

package/template/.aioson/docs/presets/workflow.config.full-merged.json

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "_about": "Full chain with @discovery-design-doc merged into @architect. Copy to .aioson/context/workflow.config.json. When discovery-design-doc is absent from the sequence, @architect runs in merged mode and produces design-doc + readiness + dev-state itself. See .aioson/docs/workflow-lean-lane.md and agents/architect.md (Architect merged mode). Runtime smoke gate stays mandatory.",
+  "feature": {
+    "MICRO": ["product", "dev", "qa"],
+    "SMALL": ["product", "analyst", "scope-check", "architect", "dev", "qa"],
+    "MEDIUM": ["product", "analyst", "architect", "pm", "scope-check", "dev", "pentester", "qa"]
+  },
+  "project": {
+    "MICRO": ["setup", "dev"],
+    "SMALL": ["setup", "product", "analyst", "scope-check", "architect", "dev", "qa"],
+    "MEDIUM": ["setup", "product", "analyst", "architect", "ux-ui", "pm", "orchestrator", "scope-check", "dev", "qa"]
+  },
+  "rules": { "required": ["dev"], "allowDetours": true }
+}

package/template/.aioson/docs/presets/workflow.config.lean.json

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "_about": "Lean lane preset. Copy to .aioson/context/workflow.config.json to opt in. See .aioson/docs/workflow-lean-lane.md. Runtime smoke gate stays mandatory in both lanes.",
+  "feature": {
+    "MICRO": ["product", "dev", "qa"],
+    "SMALL": ["product", "sheldon", "dev", "qa"],
+    "MEDIUM": ["product", "sheldon", "dev", "qa"]
+  },
+  "project": {
+    "MICRO": ["setup", "dev"],
+    "SMALL": ["setup", "product", "sheldon", "dev", "qa"],
+    "MEDIUM": ["setup", "product", "sheldon", "dev", "qa"]
+  },
+  "rules": { "required": ["dev"], "allowDetours": true }
+}

package/template/.aioson/docs/product/prd-contract.md

@@ -1,11 +1,11 @@
----
-description: "Product PRD contract — exact PRD structure, visual identity block, output paths, and next-step routing."
-agents: [product]
-modes: [executing]
-task_types: [prd-writing, prd-finalization, output-contract, artifact-writing]
-load_tier: trigger
-triggers: [writing PRD, updating PRD, PRD contract, output path, next-step routing, visual identity]
----
+---
+description: "Product PRD contract — exact PRD structure, visual identity block, output paths, and next-step routing."
+agents: [product]
+modes: [executing]
+task_types: [prd-writing, prd-finalization, output-contract, artifact-writing]
+load_tier: trigger
+triggers: [writing PRD, updating PRD, PRD contract, output path, next-step routing, visual identity]
+---
 
 # Product PRD Contract
 
@@ -98,15 +98,15 @@ After the PRD is produced:
 | classification | Next step |
 |---|---|
 | MICRO | `@dev` |
-| SMALL | `@analyst` |
-| MEDIUM | `@analyst` then `@architect` → `@ux-ui` → `@pm` → `@orchestrator` |
+| SMALL | `@sheldon` (lean default) |
+| MEDIUM | `@orchestrator` (maestro spec authority) |
 
 ### New feature (`prd-{slug}.md`)
 
 | feature complexity | Next step |
 |---|---|
 | MICRO | `@dev` |
-| SMALL | `@analyst` |
-| MEDIUM | `@analyst` → `@architect` → `@scope-check` → `@dev` → `@qa` |
+| SMALL | `@sheldon` (lean default) |
+| MEDIUM | `@orchestrator` (maestro) → `@dev` → `@pentester` → `@qa` |
 
 Assess feature complexity from the conversation and state the next agent explicitly.

package/template/.aioson/docs/prototype-contract.md

@@ -62,14 +62,28 @@ the approved PRD wins and the prototype is updated to match.
 - **@dev** — the prototype is the development source for UI and interactions. Reproduce its screens and Core
   interactions against the real stack. Never ship a Core action the prototype demonstrates (e.g. "add card",
   "create board", "manage members") while the build lacks it.
+- **@qa** — for a feature with a prototype, the Core interactions are verified through the **Runtime smoke
+  gate**: build + migrate-apply + boot + Core happy-path on the running stack, with the aios-qa browser report
+  (`aioson qa:run`/`qa:scan`) required, not optional. Source inspection ("the API call appears in the source")
+  is **not** parity evidence.
 - **@validator** — verifies prototype-derived acceptance criteria as part of the normal binary contract in
-  `harness-contract.json`. It does **not** read the prototype directly (its context sandbox forbids
-  PRDs/artifacts); the criteria authored by `@analyst` are what it checks.
+  `harness-contract.json`. It does **not** read the prototype's behavior to judge the product; but at its
+  **Contract-integrity precheck** it reads `prototype-manifest.md` solely to confirm the contract carries the
+  §2c runtime-gate criteria (`RG-build`/`RG-migrate`/`RG-boot`/`RG-smoke`) for the Core interactions. A runtime
+  feature whose contract has no `RG-*` criteria is rejected (`ready_for_done_gate: false`) before scoring.
 
 ## Completeness
 
 A feature with a prototype is not "ready for done" until every Core screen and interaction the prototype
-demonstrates is either built and verified, or explicitly deferred in the PRD's `## Out of scope`.
+demonstrates is either **built and verified on the running stack**, or explicitly deferred in the PRD's
+`## Out of scope`.
+
+**Parity is proven by running, not by reading.** A Core interaction counts as built only when it works end to
+end against the real backend/DB — never when a source-string assertion shows the API call *appears* in the
+code, and never when a structural "parity" unit test passes. The prototype is mock-only; the implementation
+must reproduce its behavior on a booted, migrated stack. This is enforced by `@qa`'s **Runtime smoke gate** and
+the `RG-build`/`RG-migrate`/`RG-boot`/`RG-smoke` criteria in `harness-contract.json` (see
+`harness-contract.md` §2c).
 
 ## Deterministic guard
 
@@ -78,4 +92,7 @@ deterministic backstop for this otherwise prose-only contract and fails on: a da
 (prototype or manifest file missing), a missing requirements bridge, or Core interactions listed in the manifest
 that no acceptance criterion echoes (`fail` = none covered, `warn` = some uncovered). It matches interaction
 names as folded substrings, so the AC must echo the manifest's interaction name (EN or pt-BR). The check never
-reads the prototype's behavior — only that the contract's structural links exist end to end.
+reads the prototype's behavior — only that the contract's structural links exist end to end. It is a
+*structural* backstop, **not** runtime proof: an AC that merely echoes an interaction name still has to be
+verified on the running stack by `@qa`'s Runtime smoke gate. Passing `prototype:check` never means a Core
+interaction actually works.

package/template/.aioson/docs/reference-identity.md

@@ -0,0 +1,94 @@
+---
+description: "Reference-image-driven visual identity — how user-provided reference images become a text identity.md the interface-design engine applies, instead of every project inheriting a fixed preset's look. Covers the schema, the two scopes, the extraction skill, the verify:artifact gate, and the cross-harness/no-vision fallback."
+agents: [setup, briefing-refiner, ux-ui]
+task_types: [design, configuration, verification]
+triggers: [identity.md, reference image, visual identity, reference-identity-extract, kind=identity, brand reference, design_skill interface-design]
+---
+
+# Reference-image-driven visual identity
+
+A fixed design preset (`clean-saas-ui`, `aurora-command-ui`, …) hardcodes a palette and a typeface, so
+every project that picks the same preset looks the same — the generic, "made-by-AI" look. The
+`interface-design` skill is the opposite: a craft **engine** whose mandate is *"if another AI would
+produce the same output, you failed."* This flow feeds that engine the user's **own references** so the
+result is specific and premium.
+
+The pipeline: **reference images → extracted once into `identity.md` (text) → the engine builds from the
+text.** The build never reads the images. This is the same move AIOSON already makes when it extracts a
+real website into a token spec — generalized so the **source** is images and the **lifetime** is
+per-briefing (or per-project brand), not a frozen preset.
+
+## Two image roles
+
+- **Visual identity** — brand color, type, texture, the *feel*. Drives the token system.
+- **Component / structure** — a board, a table, a screen the user wants. Drives **structure only**; its
+  own colors/fonts are ignored. Feeds `prototype-forge`'s surface map.
+
+Synthesis = **apply the identity to the structure.** This is why you do not want "component skills": a
+component skill smuggles in its own fixed identity and reintroduces the sameness. A component *image*
+contributes layout, and the identity comes from the identity images.
+
+## The `identity.md` record
+
+One text file the build consumes. Frontmatter mirrors the proven extracted-token shape; sections map to
+the `interface-design` token families plus its Phase-1 anti-sameness anchors. Authored by the
+`reference-identity-extract` process skill (see its `SKILL.md` for the exact schema).
+
+- **Frontmatter:** `kind`, `scope` (`briefing` | `brand`), `slug`, `source` (`references` | `intent`),
+  `generated_by`, `generated_at`, `confidence`, `theme`, `base_unit`.
+- **Sections:** `## Design pillars`, `## Palette` (real hex), `## Typography`, `## Spacing & layout`,
+  `## Radius & depth` (exactly one depth strategy), `## Motion`, `## Signature moves`, `## Anti-goals`,
+  `## Component structure notes`, `## Provenance` (generic — never names an external source).
+- `source: references` (filled from images) vs `intent` (image-less fallback via interface-design's own
+  Phase 0). **Same shape either way**, which is what makes it gateable and harness-portable.
+
+## Two scopes
+
+| scope | record | images |
+|---|---|---|
+| **Per-briefing** (default) | `.aioson/briefings/{slug}/identity.md` | `.aioson/briefings/{slug}/references/{identity,structure}/` |
+| **Project brand** | `.aioson/context/identity.md` | `.aioson/context/brand-references/{identity,structure}/` |
+
+**Resolution order** (identical for `@ux-ui` and `prototype-forge`): per-briefing → project brand →
+none (then `interface-design` Phase 0 governs). The **text record is canonical and committed**; the
+images are raw source and may be `.gitignore`d — extraction runs once, so the build never needs them
+again.
+
+## How it runs
+
+- **`@briefing-refiner`** (prototype mode) — when a rich-surface product would benefit from a visual,
+  it offers reference-image intake: the user drops images into `references/{identity,structure}/`, the
+  agent loads `reference-identity-extract`, writes `identity.md`, and `prototype-forge` builds from it.
+  No images → it skips and `interface-design` runs intent-first. Always optional, never blocking.
+- **`@setup`** — for `site`/`web_app`, the recommended visual route is *interface-design + reference
+  images* (sets `design_skill: interface-design`; the concrete look comes from `identity.md`). The
+  fixed presets remain an explicit alternative.
+- **`@ux-ui`** — Step 0 loads `identity.md` as the **identity input** the single interface-design engine
+  applies. It is **not** a second design skill: exactly one design skill is loaded, and `identity.md`
+  parameterizes it. This does not weaken the ONE-SKILL-ONLY rule.
+
+## The gate
+
+`aioson verify:artifact . --kind=identity --file=<path>` proves the record is complete — the token
+skeleton plus both anti-sameness anchors (`## Design pillars` + `## Signature moves`) plus the structure
+section are present, and no placeholder or unfilled hex slipped through. Build-free, deterministic, the
+periphery analog of the code pipeline's `SG-*` gates. The extraction skill runs it `--advisory` before
+handing back. Path-resolved via `--file` because the record lives in either scope.
+
+## Cross-harness & no-vision
+
+The extraction pass is the **only** vision step. On a vision-less harness, either run extraction once on
+a vision-capable harness, or hand-author `identity.md` from the schema — the gate then proves it is
+complete. The build is identical in both cases because it reads only the text. This is the same reason
+gates are engine-driven rather than hook-driven: the portable artifact crosses harnesses; the
+host-specific capability does not.
+
+## Notes
+
+- **Vision is non-deterministic** — two extractions of one image can differ. That is exactly why the
+  text record exists: `identity.md` is the frozen, user-editable source of truth, and the build off it
+  is deterministic.
+- **Image storage** — reference images are binary and can bloat git. The text record is canonical and
+  committed; images are optional and may be `.gitignore`d at the project level.
+- **Provenance discipline** — `## Provenance` describes sources by type only. Never name an external
+  product, brand, site, or tool in any artifact.

package/template/.aioson/docs/sheldon/harness-contract.md

@@ -15,10 +15,16 @@ Run **after** writing `sheldon-enrichment-{slug}.md`, gated by `project.context.
 
 | Classification | Action |
 |---|---|
-| MICRO | Skip entirely. No contract, no progress.json. |
-| SMALL | Produce `progress.json` only (no `harness-contract.json`). |
+| MICRO | Skip entirely — **unless it is a runtime feature** (`has_api`/DB/prototype): then produce a minimal `harness-contract.json` (just the §2c `RG-*` criteria) + `progress.json`. |
+| SMALL | Produce `progress.json` only — **plus `harness-contract.json` with the §2c `RG-*` criteria when it is a runtime feature**, so `harness:check` can enforce the runtime gate. |
 | MEDIUM | Produce both `harness-contract.json` and `progress.json`. |
 
+A **runtime feature** (`has_api` / DB / migrations / `## Prototype reference`) therefore carries the `RG-*`
+runtime gate at **every** classification. The CLI deterministically blocks the subset it can locate on disk
+(prototype manifests and migration/Prisma paths from progress/git evidence) when the runtime contract is missing
+or has no `RG-*`; the Play `has_api` case still requires the `@validator` Step 0 judgment because that flag lives
+inside the target app. Non-runtime MICRO/SMALL keep the lightweight path (no contract).
+
 ## Steps
 
 ### 1. Initialize stub
@@ -57,31 +63,139 @@ Authoring rules for `verification`:
 
 - **Prefer the project's own test runner** (`node --test tests/x.test.js`, `npm test -- --grep "..."`, `pytest tests/test_x.py`). A criterion backed by a real test is the gold standard.
 - **One-liner assertions** when no test exists yet: `node -e "const m = require('./src/x'); process.exit(typeof m.parseX === 'function' ? 0 : 1)"`.
-- **Deterministic only**: no network calls, no wall-clock dependence, no interactive prompts.
+- **Deterministic only**: no network calls, no wall-clock dependence, no interactive prompts. *(Exception: the runtime-gate criteria in §2c — `build`/`migrate`/`boot`/`smoke` — MAY provision an ephemeral DB and boot the app. That setup is the point, not a violation.)*
 - **Cross-platform**: single commands or npm scripts — avoid shell chaining (`&&`, `||`) and POSIX-only utilities (`grep`, `test -f`) on Windows-first projects; use `node -e` for file/shape assertions instead.
-- **Self-contained**: the command must pass/fail on a clean checkout after install — no hidden setup steps.
+- **Self-contained**: the command must pass/fail on a clean checkout after install — no hidden setup steps. *(Runtime-gate criteria may require `db:up`/`migrate reset` as their declared first step; declare it inside the `verification`, never as a hidden prerequisite.)*
 - A `binary: true` criterion **without** `verification` remains valid (judged by `@validator`, as before), but the contract schema emits a coverage warning — treat each one as debt and justify it in the enrichment log.
 
+### 2c. Runtime gate criteria — MANDATORY for runtime features
+
+A contract whose criteria are all unit/component test commands (e.g. `pnpm test -- <file>`) proves the
+**tests** pass, not that the **app** runs. Tests mock the database, the auth SDK and the network; a feature
+can be 100% green on unit tests while its migrations never applied, its UI was never wired to the API, and
+the process never booted. To close that gap, any feature that ships a runtime surface MUST carry criteria that
+exercise the **real, running stack** — not only mocks.
+
+A feature is a **runtime feature** when ANY of these holds:
+
+- `manifest.json` has `has_api: true`, declares a server/process, or a Play runtime; or
+- the feature creates or changes a database / Prisma schema / migrations; or
+- the feature carries a `## Prototype reference` (a clickable prototype whose Core interactions must work).
+
+For a runtime feature, add these criteria (use the project's OWN commands; drop a row only with a written
+reason in the enrichment log):
+
+| id | what it proves | example `verification` (adapt to the project) |
+|----|----------------|-----------------------------------------------|
+| `RG-build` | the app compiles for real, not a mocked subset | `pnpm build` · `npm run build` · `tsc -p .` |
+| `RG-migrate` | migrations **apply** to a fresh DB — not just exist as files | `prisma migrate reset --force` (or `migrate deploy`) against an ephemeral/throwaway DB |
+| `RG-boot` | server + client start without crashing | start the process and probe health, e.g. `node scripts/smoke-boot.mjs` hitting `/api/health` → 200 |
+| `RG-smoke` | the prototype's Core happy-path works on the running stack | `aioson qa:run` / `aioson qa:scan`, or an e2e/integration run that drives the **real** endpoints/UI end-to-end |
+
+**Hard rules:**
+
+- A runtime-feature contract containing **zero** of {`RG-build`, `RG-migrate`, `RG-boot`, `RG-smoke`} is
+  **invalid** — treat it as a coverage *error*, not a warning, and do not declare the contract final.
+  `@validator` rejects such a contract at its Contract-integrity precheck.
+- **No duplicate verification.** Two `binary: true` criteria must never carry the **same** `verification`
+  command. Each criterion maps to a distinct check. (Padding 11 criteria out of 6 commands is exactly how a
+  hollow contract scores "11/11".) `RG-migrate` and `RG-boot` are separate criteria with separate commands.
+- `RG-smoke` must drive at least the prototype-manifest's **Core** interactions for the feature
+  (create / list / switch / edit / archive of the primary objects), end to end — never a mocked unit of one
+  of them, and never a static source-string assertion that an API call *appears* in the code.
+- These criteria are first-class binary criteria: `aioson harness:check` runs them like any other, and their
+  exit code is the verdict. If the project lacks a smoke/boot harness, that harness is itself part of `@dev`'s
+  scope — do not downgrade `RG-smoke` to a unit test to make it "self-contained".
+
+> **CLI backstop (deterministic).** `aioson harness:check . --slug={slug}` enforces the first two hard rules
+> itself, not only through `@validator`, and `workflow:next --complete=dev|qa` / `feature:close --verdict=PASS`
+> call the same integrity gate before advancing. When the CLI detects a runtime surface it can locate
+> deterministically — a `.aioson/briefings/{slug}/prototype-manifest.md`, or a migration/Prisma path in
+> `progress.completed_steps`, `progress.changed_files`, or the git changed-file set — a missing contract is
+> blocked, a contract with **no** `RG-*` criterion fails with `missing_runtime_gate`, and two binary criteria
+> sharing one `verification` command fail with `duplicate_verification`; both flip the check's `ok` to `false`.
+> The Play `manifest.json` `has_api` trigger lives in the target app and is **not** locatable from the framework
+> in all projects — for that case the `@validator` Step 0 precheck remains the enforcer, and `RG-smoke` actually
+> exercising Core (vs. a unit test wearing the id) is always a `@validator` judgment. In an **untracked** session
+> (plain slash activation, no `workflow:next`), `aioson agent:epilogue --agent=dev|qa` surfaces the same check as a
+> non-blocking **advisory** `contract:integrity` step — a signal in the dashboard trail, not a gate; only the
+> tracked `workflow:next` / `feature:close` paths block. Treat a green `harness:check` as necessary, not sufficient.
+
+### 2d. Static gate criteria (SG-*) — build-independent proof
+
+`RG-*` criteria run a command (a build, a migrated DB, a booted app). They are
+the truth, but they are **expensive** — `aioson harness:check` runs them once, at
+the last gate (`@qa`, else `@dev`). They also cannot run until the app builds.
+
+An **SG-* (static gate)** criterion proves a claim by **reading the changed
+files** instead of running them: a required pattern is present (the code was
+actually written / wired) and a forbidden pattern is absent (no placeholder,
+stub or anti-pattern snuck in). It is pure `fs + RegExp + parse` — no shell, no
+build — so it costs milliseconds and the contract-integrity gate evaluates it at
+**every** stage (`@dev`-done and `@qa`-done), even when the runtime checks are
+deferred. That makes it the cheap layer that catches "claimed done but stubbed
+it / left a placeholder / never wired `requireAuth`" the instant it happens,
+on any model, cross-platform.
+
+Add an SG-* criterion when an AC has a concrete, greppable signature — a symbol
+that must be called, an export that must exist, an env var that must be read, an
+anti-pattern that must not appear — that you want proven without booting the app:
+
+```json
+{
+  "id": "SG-auth-wired",
+  "description": "auth middleware is wired into the protected router",
+  "assertion": "requireAuth is applied in src/routes/private.ts",
+  "binary": true,
+  "files": ["src/routes/private.ts"],
+  "must_match": ["requireAuth\\(", "export const privateRouter"],
+  "must_not_match": ["TODO", "as any", "not implemented"]
+}
+```
+
+Semantics:
+
+- `must_match` — **OR across files**: each pattern must appear in **≥ 1** of `files[]`.
+- `must_not_match` — **absent in all**: no pattern may appear in **any** of `files[]`.
+- Each `files[]` entry is also **parse-checked** (`JSON.parse` for `.json`,
+  `node --check` for `.js/.mjs/.cjs`) to catch a truncated/corrupted write; a
+  declared file that does not exist fails the criterion.
+- An invalid regex degrades to a literal-substring test — a typo never crashes the gate.
+
+**Rules:**
+
+- Use the `SG-` id prefix (mirrors `RG-` / `SEC-`).
+- A criterion is **either** runtime (`verification` command) **or** static
+  (`must_match`/`must_not_match`), **never both** — split into two criteria.
+- A static criterion **requires** a non-empty `files[]` to read.
+- SG-* does **not** replace `RG-*`: a static `must_match` proving an API *call
+  appears in source* is not proof the endpoint *runs*. Keep the `RG-smoke`
+  runtime gate; SG-* is the cheap, early, build-independent complement.
+
+For a **project-wide** sweep of the same anti-patterns (not tied to one AC), run
+`aioson audit:code . --json` — the categorized static scan (`TODO` /
+`ANTI_PATTERN` / `DEAD_CODE` / `DUPLICATION`) `@qa` consumes one category at a time.
+
 ### 3. Set `contract_mode`
 
-By classification and risk surface, using the modes accepted by the harness schema:
-
-- **SMALL** → `safe`
-- **MEDIUM (default)** → `builder`
-- **MEDIUM with sensitive surface** (auth, money, ownership, secrets, uploads, external URLs) → `safe`
-- **Explicit user-approved long autonomous run** → `autopilot`
+By classification and risk surface, using the modes accepted by the harness schema:
+
+- **SMALL** → `safe`
+- **MEDIUM (default)** → `builder`
+- **MEDIUM with sensitive surface** (auth, money, ownership, secrets, uploads, external URLs) → `safe`
+- **Explicit user-approved long autonomous run** → `autopilot`
 
 ### 4. Set `governor` block
 
-Safe defaults for a normal MEDIUM `builder` contract:
-
-```json
-{ "max_steps": 30, "cost_ceiling_tokens": 1000000, "error_streak_limit": 5 }
-```
-
-- `safe` applies the tight preset for risky or bounded runs.
-- `builder` applies the normal MEDIUM preset.
-- `autopilot` applies the largest preset and requires explicit user approval.
+Safe defaults for a normal MEDIUM `builder` contract:
+
+```json
+{ "max_steps": 30, "cost_ceiling_tokens": 1000000, "error_streak_limit": 5 }
+```
+
+- `safe` applies the tight preset for risky or bounded runs.
+- `builder` applies the normal MEDIUM preset.
+- `autopilot` applies the largest preset and requires explicit user approval.
 
 ## Authoring rules
 
@@ -96,14 +210,14 @@ Safe defaults for a normal MEDIUM `builder` contract:
 ### `harness-contract.json`
 
 ```json
-{
-  "feature": "<slug>",
-  "contract_mode": "balanced | safe | builder | autopilot",
-  "governor": {
-    "max_steps": 50,
-    "cost_ceiling_tokens": 1000000,
-    "error_streak_limit": 5
-  },
+{
+  "feature": "<slug>",
+  "contract_mode": "balanced | safe | builder | autopilot",
+  "governor": {
+    "max_steps": 50,
+    "cost_ceiling_tokens": 1000000,
+    "error_streak_limit": 5
+  },
   "criteria": [
     {
       "id": "C1",
@@ -111,12 +225,24 @@ Safe defaults for a normal MEDIUM `builder` contract:
       "assertion": "...",
       "binary": true,
       "verification": "node --test tests/foo.test.js"
+    },
+    {
+      "id": "SG-1",
+      "description": "...",
+      "assertion": "...",
+      "binary": true,
+      "files": ["src/x/y.ts"],
+      "must_match": ["export function parseX"],
+      "must_not_match": ["as any", "TODO"]
     }
   ]
 }
 ```
 
-`verification` is optional per criterion (legacy contracts remain valid), executed via `aioson harness:check` with exit code 0 = pass.
+A criterion is **runtime** (carries `verification`, executed via `aioson
+harness:check` with exit code 0 = pass) **or** **static** (carries `files[]` +
+`must_match`/`must_not_match`, evaluated build-free — see §2d). Both are
+optional per criterion; a criterion with neither stays an `@validator` judgment.
 
 ### `progress.json`
 
@@ -138,3 +264,4 @@ Safe defaults for a normal MEDIUM `builder` contract:
 - **No verifiable ACs in PRD** — go back to enrichment with `@product` and add concrete assertions before generating a contract.
 - **All ACs are advisory** — flag to user; the harness adds no value. Skip contract generation, document the decision in `sheldon-enrichment-{slug}.md`.
 - **`harness:init` CLI missing** — write stubs manually, but record in handoff that CLI was unavailable so `@dev` can install it.
+- **All criteria are unit tests on a runtime feature** — the contract proves the tests pass, not that the app runs. This is the failure that ships a green-but-broken build (migrations never applied, UI never wired, process never booted). Add the §2c runtime-gate criteria before declaring the contract final; a runtime-feature contract without them is invalid.

package/template/.aioson/docs/verification-config.md

@@ -0,0 +1,82 @@
+---
+description: "Verification sub-agent config (verification.json) — which verifiers run, when, and on which host/model; native vs external dispatch."
+agents: [dev, qa, validator]
+task_types: [verification, configuration]
+triggers: [verification config, verification.json, sub-agent verification, native vs external, cross-vendor auditor]
+---
+
+# Verification sub-agent config — `.aioson/config/verification.json`
+
+Controls **which** verification sub-agents run, **when**, and on **which model** — resolved per host harness. Consumed by the `@dev` phase-loop (per-phase checks) and the post-dev review cycle (end-of-feature gate). Auto-generated on `aioson init`/`update` and hand-editable: your values survive updates (additive merge), only `version` is framework-owned.
+
+## The one rule that trips people up: `native` vs `external`
+
+Dispatch is **keyed by the host harness** (`claude` / `codex` / `opencode`), and each host has two modes:
+
+- **`native`** — an in-harness sub-agent. On **Claude Code** it runs a **Claude model tier** (e.g. `sonnet-4.6`, `opus-4.8`). On codex/opencode it runs that CLI's own configured model. You **cannot** run a codex/GPT model as a *native Claude Code sub-agent* — different vendor, different process.
+- **`external`** — spawn a **different vendor CLI** as a read-only auditor (`aioson verify:implementation --tool=...`). This is the *only* way to bring a cross-vendor model in while hosted elsewhere. Heavier; reserve for a second opinion on sensitive surfaces — see `cross_check`.
+
+So the config never asks "run codex inside claude". Each host row just names the right **native** model for whoever is hosting; `cross_check` is the explicit, opt-in cross-vendor escape hatch.
+
+## Per-agent fields
+
+```jsonc
+"qa": {
+  "enabled": true,                 // true | false | "auto" (framework decides)
+  "triggers": ["per-phase", "end-of-feature"],
+  "dispatch": {
+    "claude":   { "mode": "native", "model": "sonnet-4.6" },
+    "codex":    { "mode": "native", "model": "configured-default" },
+    "opencode": { "mode": "native", "model": "configured-default" }
+  },
+  "report": "qa-report-{slug}.md"  // {slug} is substituted at run time
+}
+```
+
+- **`enabled`** — `true` / `false` / `"auto"`. `"auto"` resolves from context: `pentester` only on a sensitive surface, `tester` on anything above MICRO, others on.
+- **`triggers`** — `per-phase` (light, cheap, runs between phases), `end-of-feature` (full gate), `sensitive-surface` (security pass). Per-phase is the cheap loop check; the full smoke runs once at `end-of-feature`.
+- **`model: "configured-default"`** — delegate to the host CLI's own configured model (don't pin one).
+- **`validator.cross_check`** — `{ "enabled": false, "mode": "external", "tool": "codex", "model": "..." }`. Flip `enabled: true` to add an independent cross-vendor verdict on the contract.
+
+## Budget (token economy)
+
+```jsonc
+"budget": {
+  "max_subagents_per_phase": 1,        // cap concurrent verifiers per phase
+  "skip_on_micro": true,               // suppress per-phase checks on MICRO
+  "full_smoke": "end-of-feature-only"  // never re-run the full runtime smoke per phase
+}
+```
+
+The whole point is **leve por fase / completo no fim**: a per-phase check confirms the slice cheaply; the expensive build+migrate+boot+happy-path smoke runs once, at the end.
+
+## Code-quality gate (`audit_code`)
+
+Controls the deterministic, build-free `aioson audit:code` scan wired into the **tracked** `workflow:next` `@dev`/`@qa` done-gate (the non-security categories: anti-patterns / TODOs / dead code / duplication; security stays with `security:audit`).
+
+```jsonc
+"audit_code": {
+  "tracked_gate": "advisory",  // "block" | "advisory" | "off"
+  "scope": "changed"           // "changed" (git diff, fast) | "full" (whole tree)
+}
+```
+
+- **`advisory`** (default) — the scan runs, persists `.aioson/context/audit-code.json`, emits a guard event on a HIGH finding, and rides a summary on the workflow result, but **never blocks** the stage. `audit:code` is a heuristic opinion, not the feature's declared contract, so it does not gate by default (and existing flows keep advancing).
+- **`block`** — a HIGH finding in scope is a **hard gate**: `@dev`/`@qa` cannot complete until it is fixed (or the policy relaxed). Use this when you want the tracked workflow to enforce code health like a runtime gate.
+- **`off`** — skip the step entirely.
+
+This is deterministic (no LLM judgment) and runs at every tracked `@dev`/`@qa` completion. `@qa` separately treats a HIGH as a Gate-D blocker in its review, and the same scan auto-fires as an advisory in `aioson agent:epilogue` for untracked sessions.
+
+> **Periphery analog:** for the **non-code** artifacts the specialized agents produce (project context, genomes, profiler reports, the discovery cache, hybrid skills, generated sites, copy, commit subjects), the same build-free philosophy is applied by `aioson verify:artifact` — see **`verify-artifact-gates.md`**.
+
+## Examples
+
+Pin qa to the cheapest Claude tier per phase:
+```json
+"qa": { "dispatch": { "claude": { "mode": "native", "model": "haiku-4.5" } } }
+```
+
+Add a cross-vendor second opinion on the contract for sensitive features:
+```json
+"validator": { "cross_check": { "enabled": true, "mode": "external", "tool": "codex", "model": "configured-default" } }
+```