@jaimevalasek/aioson 1.30.2 → 1.36.0

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" } }
+```

package/template/.aioson/docs/verify-artifact-gates.md

@@ -0,0 +1,91 @@
+---
+description: "Artifact done-gates (verify:artifact) — build-free, model-agnostic completeness/integrity checks for the non-code artifacts the specialized agents produce before they register done."
+agents: [setup, genome, profiler-researcher, profiler-enricher, profiler-forge, discover, orache, design-hybrid-forge, site-forge, copywriter, committer, squad]
+task_types: [verification, configuration]
+triggers: [verify:artifact, artifact gate, done gate, artifact done-gate, placeholder gate, kind=]
+---
+
+# Artifact done-gates — `aioson verify:artifact`
+
+The periphery analog of the code pipeline's `SG-*` / `RG-*` harness gates: a
+build-free **"done = proven, not asserted"** check for the **non-code artifacts**
+the specialized agents produce. Where `audit:code` scans code quality and the
+harness contract gates a feature, `verify:artifact` proves a produced artifact is
+complete and well-formed before the agent calls `agent:done`.
+
+The failure mode it closes is the one the runtime smoke gate closed for code: an
+agent self-declaring done with no proof — a `project.context.md` with an invalid
+enum, a genome missing its manifest, a research report with an unfilled
+`[Full Name]`, a generated site that never built.
+
+```bash
+aioson verify:artifact . --kind=<kind> [--slug=<slug>] [--file=<path>] [--advisory] [--strict]
+```
+
+A `kind` routes to either an **existing validator** or a declarative **SG-\***
+**ruleset** over the shared static-criteria engine — pure `fs` + `RegExp` +
+`JSON.parse` / `node --check` (no shell, no build, cross-platform by
+construction). Adding a gate to a new agent is a registry entry plus one
+done-gate line, not a bespoke implementation.
+
+| kind | agent | backed by | default |
+|---|---|---|---|
+| `project-context` | `@setup` | `validateProjectContextFile` (required fields, enums, frontmatter parse) | blocking |
+| `genome` | `@genome`, `@profiler-forge` | `genome:doctor` (manifest/references/anchor/Track-4.3 quality) | blocking |
+| `research-report` | `@profiler-researcher` | ruleset (frontmatter + inventory/extracted/gaps sections, no template token) | blocking |
+| `enriched-profile` | `@profiler-enricher` | ruleset (exec summary / psychometric / operational method / trait interactions) | blocking |
+| `bootstrap` | `@discover` | ruleset (all 4 cold-start files exist with real frontmatter, no placeholder) | blocking |
+| `orache-report` | `@orache` | ruleset, resolved via `--file` (7 dimensions + impact + source) | blocking |
+| `hybrid-skill` | `@design-hybrid-forge` | ruleset (`.skill-meta.json` parses + sources, SKILL.md, both previews) | blocking |
+| `site` | `@site-forge` | static floor + `npm run build` on the real stack | blocking |
+| `copy` | `@copywriter` | ruleset (placeholder / Lorem / TODO / unfilled-token scan) | advisory |
+| `commit-message` | `@committer` | subject heuristics (`--file` draft or HEAD commit) | advisory |
+
+## Contract
+
+- Every gate returns a uniform `{ ok, issues[], warnings[] }`, persists
+  `.aioson/context/verify-artifact-<kind>.json`, and sets **exit 1** on a hard
+  failure — **unless `--advisory`** (warn-only, always exit 0). `--strict`
+  promotes warnings to blocking issues.
+- `--slug` resolves a slug-keyed artifact path; `--file` resolves a
+  caller-known / date-stamped path. A kind that needs one fails with a clean
+  usage error instead of probing a `null/` path.
+- `--no-build` (kind=`site`) runs the static floor only — a fast mid-work
+  re-check that skips the `npm run build` runtime floor.
+
+## Auto-fire at `agent:done`
+
+These gates do not depend on each agent remembering to run its `## Done gate`
+line. `aioson agent:done` resolves the calling agent to its artifact kind
+(`src/artifact-kinds.js`) and runs the matching `verify:artifact --advisory`
+itself — so the check fires at the one call every agent already makes at session
+end (and rides on `agent:epilogue`, which wraps `agent:done`):
+
+- **Self-resolving kinds** (`setup`→`project-context`, `discover`→`bootstrap`,
+  `committer`→`commit-message`) run with no extra input — fully deterministic,
+  no markdown dependency.
+- **Locator-keyed kinds** run when the agent threads its locator into that same
+  call (`--slug` / `--file` / `--dir`, which the agent's Observability line now
+  carries); without it, `agent:done` surfaces a one-line hint naming the exact
+  command, so the gate is visible rather than silently skipped.
+
+Always advisory at this layer: a failed or skipped check is surfaced but never
+flips the session-end result. The explicit per-agent `## Done gate` stays as the
+agent-facing "check and FIX" step; this is the deterministic engine net beneath
+it — the periphery analog of how `audit:code` auto-fires in `agent:epilogue`.
+
+## `@squad` is gated separately
+
+A squad ships through its own `aioson squad:validate` (structural: manifest
+schema, required files, every declared executor file exists, no duplicate slugs,
+canonical paths) plus its source-grounded multi-model **eval-gate** — both
+promoted from opt-in into the default `validate` step. See `@squad`'s Done gate.
+
+## Why this shape
+
+Same philosophy as the `audit_code` gate in `verification-config.md`: build-free,
+model-agnostic, deterministic, and cheap enough to run at **every** agent's done
+gate. It does not judge subjective quality (resonance, voice, persuasiveness) —
+those stay with each agent's own checklist. It proves the artifact is *there*,
+*structured*, and *not a placeholder*, which is exactly what self-asserted "done"
+was silently skipping.

package/template/.aioson/docs/workflow-lean-lane.md

@@ -0,0 +1,129 @@
+---
+name: workflow-lean-lane
+agents: [setup, product, sheldon, dev, qa, validator, neo, orchestrator]
+modes: [planning]
+task_types: [workflow, routing, configuration]
+load_tier: trigger
+triggers: [lean lane, workflow.config.json, fewer agents, menos é mais, lean pipeline]
+---
+
+# Workflow Lean Lane (SMALL default; opt-in for MEDIUM)
+
+SMALL features now run the **lean chain by default**, and MEDIUM runs the **`@orchestrator` maestro lane**
+(`@product → @orchestrator → @dev → @pentester → @qa`), where `@orchestrator` fans out to
+`@analyst`/`@architect`/`@pm` (+ `@ux-ui` when UI-heavy) as sub-agents and consolidates one gated spec
+package, with `@scope-check`, `@discovery-design-doc`, and `@ux-ui` available as opt-in detours. The older heavy chain (`product → analyst → scope-check → architect →
+discovery-design-doc → pm → dev → qa`) is no longer a built-in default, but its spec hops can be opted
+back in. The bottleneck was never "too few design documents", it was the absence of a gate that runs the
+real app (now fixed: see `.aioson/docs/sheldon/harness-contract.md` §2c and `@qa`'s Runtime smoke gate).
+
+The **lean lane** removes the intermediate hops and makes `@sheldon` the single spec authority:
+
+```
+product (PRD) → sheldon (enrich + ACs + design + plan + harness-contract) → dev → qa → (validator detour)
+```
+
+`@sheldon` runs in **Lean lane mode (RF-LEAN)** and produces, in one pass, what analyst/architect/
+discovery-design-doc/pm would have produced (requirements + ACs, design-doc + readiness, implementation plan,
+and the §2c runtime-gated harness contract). `@dev` implements from that plan using the project's design skill;
+`@qa` runs the Runtime smoke gate; `@validator` runs as a detour when a harness contract exists.
+
+## When to use which lane
+
+| Use the **lean lane** when… | Opt into the **full chain** when… |
+|---|---|
+| Most features — bounded scope, a single product surface, a clear prototype | Genuinely large or multi-domain scope |
+| You want velocity and one spec authority | Sensitive surface (money, multi-tenant ownership, regulated data) that wants independent architecture + scope-check + adversarial review as distinct gates |
+| The team trusts `@sheldon` to own the bridge | You want the readiness/scope-check checkpoints to be separate agents |
+
+The **runtime smoke gate is mandatory in both lanes** for every runtime surface the framework can prove from
+local artifacts. The CLI blocks detectable runtime features (prototype manifest or migration/Prisma evidence)
+without a valid `RG-*` contract; `@validator` still owns the target-app-only `has_api` judgment.
+
+## How to opt in
+
+SMALL already ships lean — no config needed. Use this preset to extend the lean shape to MEDIUM (or to pin it
+explicitly). Drop this file at `.aioson/context/workflow.config.json` (the CLI's `readWorkflowConfig` merges it over the
+built-in defaults — per-classification arrays replace the defaults). Then run `aioson workflow:next .` as usual.
+
+A ready-to-copy preset lives at `.aioson/docs/presets/workflow.config.lean.json`:
+
+```json
+{
+  "version": 1,
+  "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 }
+}
+```
+
+`allowDetours: true` keeps `@validator` (harness contract present) and `@tester`/`@pentester` (fired by `@qa`'s
+triggers) available as detours — they are not in the static sequence in either lane.
+
+Autopilot (`auto_handoff: true`) drives only the **post-dev** cycle (`@dev → @qa → …`) in the lean lane:
+`@product`/`@sheldon` always hand off manually (upstream-agent policy), so there is nothing to auto-chain before
+`@dev`. This matches the MEDIUM maestro lane, whose `@product`/`@orchestrator` pre-dev handoffs are also manual —
+so the lean lane loses no automation it was ever supposed to have.
+
+Running the agents by hand (slash commands) is equivalent: activate `@product → @sheldon → @dev → @qa` and skip
+analyst/architect/discovery-design-doc/pm. No config file is needed for the manual path.
+
+## Full-merged chain (heavier, opt-in)
+
+The lean/maestro defaults are enough for most work. When a project genuinely wants the heavier multi-agent
+chain back — independent `@analyst`, `@architect`, and `@pm` as distinct gates — drop the **full-merged**
+preset at `.aioson/context/workflow.config.json` (ready-to-copy at
+`.aioson/docs/presets/workflow.config.full-merged.json`): it is that chain with `discovery-design-doc`
+removed. On this full-merged detour, when the active sequence routes `@architect` → `@dev` while omitting
+`@discovery-design-doc`, `@architect` runs in **merged mode** (see `agents/architect.md` → *Architect merged
+mode*) and produces the design-doc + readiness + dev-state itself, then hands off to `@dev`. Merging `@architect` +
+`@discovery-design-doc` keeps the readiness gate (the cheap, valuable part) while dropping the redundant
+second file-level-plan hop; it is a velocity change, not a correctness one — the runtime gate is what
+prevents the green-but-broken outcome.
+
+```json
+{
+  "version": 1,
+  "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 }
+}
+```
+
+## What this does NOT change
+
+- The override mechanism is unchanged — `readWorkflowConfig` still merges `workflow.config.json` over the
+  built-in defaults (per-classification arrays replace the defaults). Only the built-in default *shape* changed
+  (SMALL ships lean, MEDIUM ships the `@orchestrator` maestro lane); the lean lane stays a project-level config +
+  agent capability, not a different engine.
+- The runtime safety gates are unchanged: `@qa`'s Runtime smoke gate, the §2c `RG-*` criteria, the CLI
+  contract-integrity backstop, and `@validator`'s target-app judgment apply identically in both lanes.
+
+## What the lean lane DOES change about the gates
+
+Removing `@analyst`/`@pm` removes the agents that produced `spec-{slug}.md` and approved the process gates
+A (requirements), B (design) and C (plan). Those gates still fire under `aioson workflow:next` — `@dev`'s
+completion checks **Gate C** against `spec-{slug}.md`, and `@qa`'s checks **Gate D** against the same file — so
+the lean lane would dead-end at `@dev` if nothing produced them. In the lean lane **`@sheldon` owns that**: its
+RF-LEAN pass writes `spec-{slug}.md` with `gate_requirements`/`gate_design`/`gate_plan: approved` and an
+`implementation-plan-{slug}.md` with `status: approved` (the hops it collapsed, after the user confirms its
+spec-authority output). Gate D / execution stays with `@qa`, which writes the `## QA sign-off` PASS into the same
+file after the Runtime smoke gate. If you run the lane by hand (slash
+commands, untracked), the gate frontmatter is informational — but writing it keeps the manual and tracked paths
+identical.

package/template/.aioson/skills/design/interface-design/references/intent-and-domain.md

@@ -19,6 +19,8 @@ If `.interface-design/system.md` exists, treat it as the visual source of truth:
 - Respect it unless the user explicitly wants a redesign.
 - Update it when you introduce a reusable pattern, token rule, or layout decision.
 
+If an `identity.md` exists (`.aioson/briefings/{slug}/identity.md`, else `.aioson/context/identity.md`), treat it as the visual source of truth too — it is the **extracted-from-references** form of `system.md`, distilled once from the user's own reference images (see `.aioson/docs/reference-identity.md`). Load its token sections and `## Component structure notes` before choosing a direction, and **apply** them rather than re-deriving a generic one. It is an input you apply, not a separate design system.
+
 If the file does not exist and the task covers more than one screen or component family, create it with:
 - Product context and UI intent
 - Chosen design direction and anti-goals