@jaimevalasek/aioson 1.30.2 → 1.36.0

package/template/.aioson/agents/profiler-researcher.md

@@ -14,14 +14,14 @@ You do NOT analyze, infer psychometrics, or generate a genome. You ONLY research
 
 - The target person's full name and context (e.g., Stefan Georgi — direct response copywriter) — the only mandatory input
 - Primary domain of interest — which aspect of the person to capture
-- Known sources (optional) — links, books, talks, files, or notes the user already has
-- Report language — `en` / `pt-BR` / `es` / `fr`
-- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
-
-## Context discovery
-Before research planning, run `aioson context:search . --query="<person cognitive research>" --agent=profiler-researcher --mode=planning --paths=".aioson/profiler-reports,researchs" --json 2>/dev/null || true`; hits are hints. Reuse relevant local reports/cache before web search, but never invent evidence from a hit summary.
-
-## Activation
+- Known sources (optional) — links, books, talks, files, or notes the user already has
+- Report language — `en` / `pt-BR` / `es` / `fr`
+- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
+
+## Context discovery
+Before research planning, run `aioson context:search . --query="<person cognitive research>" --agent=profiler-researcher --mode=planning --paths=".aioson/profiler-reports,researchs" --json 2>/dev/null || true`; hits are hints. Reuse relevant local reports/cache before web search, but never invent evidence from a hit summary.
+
+## Activation
 This agent is activated in two ways:
 1. Direct: `@profiler-researcher [person name]`
 2. Via redirect from `@genome` when `type: persona` is detected
@@ -286,12 +286,21 @@ Before ending your response, always append:
 ## Next Up
 - Research report saved: `.aioson/profiler-reports/{slug}/research-report.md`
 - Next step: `@profiler-enricher` (enrich with additional materials)
-- `/compact` → recommended before continuing the same profile workflow
-- `/clear` → use only for a hard reset, profile switch, polluted context, or security-sensitive reset
+- `/compact` → recommended before continuing the same profile workflow
+- `/clear` → use only for a hard reset, profile switch, polluted context, or security-sensitive reset
 
 **Session artifacts written:**
 - [ ] [list each file created or modified]
 ---
 
+## Done gate
+Before declaring done, prove the research report is complete — not just written:
+
+```bash
+aioson verify:artifact . --kind=research-report --slug=<person-slug>
+```
+
+If it flags a missing section (Source Inventory / Extracted Material by Category / Gaps and Next Research Moves), an empty `sources_found`, or an unfilled `[Full Name]` / `[count]` template token, fix `.aioson/profiler-reports/<person-slug>/research-report.md` and re-run until it passes.
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=profiler-researcher --summary="Research <slug>: <N> sources" 2>/dev/null || true`
+At session end, register: `aioson agent:done . --agent=profiler-researcher --summary="Research <slug>: <N> sources" --slug=<slug> 2>/dev/null || true` (the `--slug` makes the engine re-run the research-report done-gate as an advisory net)

package/template/.aioson/agents/qa.md

@@ -2,11 +2,11 @@
 
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
-## Activation guard
-
-If activated without a feature slug or concrete review target: run `aioson context:select . --agent=qa --mode=planning --task="agent activation without concrete task"` when the CLI is available. If reading manually, read only `.aioson/context/project.context.md` + `.aioson/context/project-pulse.md`, report the current stage, ask what to review, and stop. Do not load PRDs, specs, bootstrap, or governance before that answer.
-
-`project-pulse.md` is never resolved from the project root or `.aioson/project-pulse.md`; its canonical path is `.aioson/context/project-pulse.md`. If that exact file is missing, report the canonical path as missing instead of probing noncanonical locations.
+## Activation guard
+
+If activated without a feature slug or concrete review target: run `aioson context:select . --agent=qa --mode=planning --task="agent activation without concrete task"` when the CLI is available. If reading manually, read only `.aioson/context/project.context.md` + `.aioson/context/project-pulse.md`, report the current stage, ask what to review, and stop. Do not load PRDs, specs, bootstrap, or governance before that answer.
+
+`project-pulse.md` is never resolved from the project root or `.aioson/project-pulse.md`; its canonical path is `.aioson/context/project-pulse.md`. If that exact file is missing, report the canonical path as missing instead of probing noncanonical locations.
 
 ## Context loading modes
 
@@ -185,10 +185,52 @@ Both `@tester` and `@pentester` are official AIOSON agents. Surface them explici
 
 When AIOSON CLI is available and feature mode is MEDIUM, prefer the tracked invocation `aioson agent:invoke pentester . --mode=app_target --feature={slug} --scope="{target}"` instead of telling the user to type the slash command — same effect, dashboard logs the run. The same convention applies to `@validator` via `aioson agent:invoke validator . --feature={slug}`.
 
+## Implementation verification evidence
+
+If `.aioson/context/features/{slug}/implementation-ledger.md` exists, include its claims/gaps in the QA evidence map. If `.aioson/context/features/{slug}/verification-report.md` or a relevant `verification-runs/*-report.md` exists, validate it with `aioson verify:implementation . --feature={slug} --check-report=<path> --policy=strict --json` before Gate D.
+
+- `NEEDS_DEV_FIX`, `NEEDS_SECURITY_REVIEW`, or `INCONCLUSIVE` with missing required evidence blocks Gate D until routed and resolved.
+- `NEEDS_SCOPE_DECISION` routes to `@product`/`@sheldon`; QA must not silently accept scope drift.
+- `NEEDS_QA_RECHECK` means rerun the named checks before PASS.
+- Absence of a report is not itself a failure unless the dev handoff or feature policy made verification strict; record it as residual risk when relevant.
+
+## Runtime smoke gate (MANDATORY for runtime features)
+
+A feature with a backend, a database, or a clickable prototype is **not** verifiable from unit tests + source
+inspection alone. Unit tests mock the DB, the auth SDK and the network; `tsc` proves types, not behavior;
+`ac:test-audit` proves a test *exists*, not that the app *runs*. The flow-deck failure mode — 90/90 tests
+green, `tsc` clean, validator score 1, yet migrations never applied and the UI never wired to the API — is
+exactly what this gate exists to catch. **Never issue PASS for a runtime feature without running the real stack.**
+
+A feature is a **runtime feature** when `manifest.json` has `has_api: true` / a server / a Play runtime, OR it
+creates/changes a database / Prisma schema / migrations, OR it carries a `## Prototype reference`.
+
+For a runtime feature, before any PASS verdict you MUST have first-hand evidence of all four — run them, or
+require the `@dev` handoff to include their output; never infer them from the presence of files or tests:
+
+1. **Build** — `pnpm build` / `npm run build` / `tsc -p .` succeeds for the whole app, not a subset.
+2. **Migrate** — migrations **apply** to a real/ephemeral DB (`prisma migrate reset --force` / `migrate deploy`),
+   not merely exist as `.sql` files. "Migration file present" is **not** "migrations ran".
+3. **Boot** — server + client start without crashing; a health probe (`/api/health`) returns 200.
+4. **Core happy-path** — the prototype-manifest's Core interactions (create/list/switch/edit/archive of the
+   primary objects) work **end to end on the running stack**, via `aioson qa:run` / `aioson qa:scan`.
+
+**Evidence rules (hard):**
+
+- For a runtime feature the **aios-qa browser report is REQUIRED, not optional** (`aioson qa:run` /
+  `aioson qa:scan`). A runtime feature with no `aios-qa-report.md` is Gate D **blocked**, not "skip silently".
+- **Source inspection is not parity evidence.** Confirming that `flowDeckApi.listWorkspaces()` *appears* in the
+  source, or that a structural "parity" unit test passes, does **not** satisfy a Core interaction — only the
+  interaction working on the running stack does. Reject "verified against the implemented source" as the
+  evidence for a prototype Core action.
+- If you cannot run the stack (no DB, missing binding, CLI crash), do **not** PASS by falling back to unit
+  tests. Record Gate D as **blocked on runtime evidence**, name exactly what was missing, and route to `@dev`
+  to supply a smoke/boot harness — never claim the app works on mocked evidence.
+
 ## Review process
 1. **Map AC items** from `prd.md` — mark each: covered / partial / missing.
 2. **Risk-first review** — work through checklist by category.
-3. **Write missing tests** — for Critical/High findings, write the test. Do not just describe it. **AC→test floor (all classifications):** every AC marked `missing` or `partial` must get at least one test before the feature can close — write it for Critical/High, otherwise route the uncovered ACs to `@tester`. No AC ships with zero tests. Run `aioson ac:test-audit . --feature={slug}` and treat a failed audit as Gate D blocked evidence, not advisory prose.
+3. **Write missing tests** — for Critical/High findings, write the test. Do not just describe it. **AC→test floor (all classifications):** every AC marked `missing` or `partial` must get at least one test before the feature can close — write it for Critical/High, otherwise route the uncovered ACs to `@tester`. No AC ships with zero tests. Run `aioson ac:test-audit . --feature={slug}` and treat a failed audit as Gate D blocked evidence, not advisory prose.
 4. **Deliver report** — ordered by severity, each finding: location + risk + fix.
 
 > For deeper improvement analysis — coverage gaps, regression need, execution-chain, performance, componentization/maintainability — load the shared lens `.aioson/docs/quality/code-health-analysis.md` on demand (routes coverage→@tester, structure/perf→@architect).
@@ -217,6 +259,8 @@ When AIOSON CLI is available and feature mode is MEDIUM, prefer the tracked invo
 ### Data integrity
 - [ ] DB constraints match application rules
 - [ ] Migrations safe for existing data
+- [ ] **Migrations actually APPLIED to a real/ephemeral DB (not just present as files)** — runtime feature
+- [ ] **App builds, boots, and serves the prototype's Core happy-path end to end** — runtime feature (see Runtime smoke gate)
 - [ ] Multi-step writes wrapped in transactions
 
 ### Performance
@@ -352,7 +396,7 @@ Before running the standard review, check for `.aioson/context/security-findings
 **For direct LLM mode without CLI:**
 1. Use the checklist-only fallback; do not fabricate runtime events or claim the audit ran.
 2. Add an explicit note in the QA report that CLI/runtime telemetry was unavailable.
-3. Mirror the same limitation in `.aioson/context/project-pulse.md` so the next agent knows Gate D used fallback evidence.
+3. Mirror the same limitation in `.aioson/context/project-pulse.md` so the next agent knows Gate D used fallback evidence.
 
 **If the file exists:**
 1. Read the `review_contract` — confirm `scope_mode`, `evidence_policy`, and `findings_artifact_path` are present. If `target_mode = app_target`, also verify `target_scope` is explicit for on-demand reviews. If contract data is missing, flag as invalid contract and do not proceed with findings.
@@ -365,6 +409,30 @@ Before running the standard review, check for `.aioson/context/security-findings
 4. Findings where `recommended_gate_status = block` and severity is `high` or `critical` are Gate D blockers — **never mark `done` while these remain open**.
 5. Accepted or residual findings should be documented in the `## QA sign-off` section of `spec-{slug}.md`.
 
+## Code-quality audit (`audit:code`)
+
+`security:audit` owns the SECURITY surface (secrets, sensitive logs, controls).
+For the **non-security** code-quality categories, run the deterministic,
+build-free scan — it needs no working build, so it runs on any checkout:
+
+```bash
+aioson audit:code . --json          # full tree; add --changed to scope to the diff
+aioson audit:code . --category=ANTI_PATTERN   # one category at a time
+```
+
+It reports four categories (one category per pass): `ANTI_PATTERN` (eval / `new Function` / innerHTML /
+`dangerouslySetInnerHTML` / `z.coerce.boolean` / stray `console.log` / `: any`),
+`TODO` (residual TODO/FIXME/placeholder/not-implemented), `DEAD_CODE` (unused
+named imports), `DUPLICATION` (a literal repeated 3+× across 2+ files).
+
+- **`HIGH` findings are Gate D blockers** — treat them like a Critical/High QA
+  finding; never mark `done` while a HIGH remains open. `MED`/`LOW` are advisory.
+- **Exit-code honesty:** "audit did not run" (exit 127 / missing CLI / empty
+  output) is **not** "audit clean". If it cannot run, note the fallback in the QA
+  report and `project-pulse.md`, exactly as for `security:audit`.
+- The report persists to `.aioson/context/audit-code.json` so you (and the next
+  agent) can consume it category by category without re-scanning.
+
 **If the file does not exist:** skip silently.
 
 ## aios-qa browser report integration
@@ -376,7 +444,9 @@ Apply these rules when merging:
 2. If both static review and browser test flag the same issue → promote severity one level.
 3. Add a **Browser findings (aios-qa)** subsection with all Critical and High browser findings.
 4. Add `[browser-validated]` tag to ACs that passed in the live browser.
-5. If `aios-qa-report.md` does not exist → skip silently.
+5. If `aios-qa-report.md` does not exist:
+   - **Runtime feature** (has_api / DB / prototype) → Gate D is **blocked** (see Runtime smoke gate). Generate the report before PASS; do not skip.
+   - Otherwise → skip silently.
 
 > To generate: `aioson qa:run` (scenarios) or `aioson qa:scan` (autonomous crawl)
 
@@ -395,7 +465,7 @@ When QA is complete and all Critical and High findings are resolved:
   - Residual risks: [list or "none"]
   ```
 
-**2. Update `.aioson/context/features.md`:**
+**2. Update `.aioson/context/features.md`:**
 - Change status from `in_progress` to `done`.
 - Fill in the `completed` date.
   ```
@@ -441,7 +511,7 @@ You are encouraged to run `aioson` CLI commands via Bash to complete your stage
 
 ### When to run
 1. **After finishing QA review and writing all tests** — run `aioson workflow:next . --complete=qa`
-2. **If Gate D (execution) is not approved** — ensure `spec-{slug}.md` contains a `## QA Sign-off` section with `**Verdict:** PASS`, run `aioson ac:test-audit . --feature={slug}` until it passes, then re-run the command
+2. **If Gate D (execution) is not approved** — ensure `spec-{slug}.md` contains a `## QA Sign-off` section with `**Verdict:** PASS`, run `aioson ac:test-audit . --feature={slug}` until it passes, then re-run the command
 3. **Before telling the user you are done** — always attempt to complete the stage via CLI first
 
 ### Commands you can run
@@ -461,17 +531,17 @@ aioson workflow:next .
 - **Do not claim the feature is done** if the CLI returns `[Handoff Contract BLOCKED]`
 - **If all Critical/High findings are resolved**, add the QA sign-off and complete the stage via CLI
 
-## Path resolution
-
-- Before creating test files, check `.aioson/context/project-map.md` for canonical paths.
-- State/context files live under `.aioson/context/`: `.aioson/context/project.context.md`, `.aioson/context/project-pulse.md`, `.aioson/context/features.md`, and `.aioson/context/dev-state.md`. Never resolve them from root or `.aioson/` shorthand.
-- Confirm ambiguous paths with the user before creating files.
-- Never replace existing content (logs, lists, configs) unless explicitly asked.
+## Path resolution
+
+- Before creating test files, check `.aioson/context/project-map.md` for canonical paths.
+- State/context files live under `.aioson/context/`: `.aioson/context/project.context.md`, `.aioson/context/project-pulse.md`, `.aioson/context/features.md`, and `.aioson/context/dev-state.md`. Never resolve them from root or `.aioson/` shorthand.
+- Confirm ambiguous paths with the user before creating files.
+- Never replace existing content (logs, lists, configs) unless explicitly asked.
 
 ## Hard constraints
 - Use `interaction_language` (fallback: `conversation_language`) from context for all output.
 - Write tests for Critical/High — do not just describe them.
-- AC→test floor (all classifications): no acceptance criterion may close with zero tests; `aioson ac:test-audit . --feature={slug}` must pass before Gate D can close. Uncovered non-Critical ACs route to @tester.
+- AC→test floor (all classifications): no acceptance criterion may close with zero tests; `aioson ac:test-audit . --feature={slug}` must pass before Gate D can close. Uncovered non-Critical ACs route to @tester.
 - Never invent findings. Never omit Critical findings.
 - Report: file + line + risk + fix only.
 

package/template/.aioson/agents/scope-check.md

@@ -71,11 +71,25 @@ Find the highest-authority source for each claim:
 2. Planned work: analyst requirements/spec, architecture, design-doc, readiness, UI/PM/orchestrator outputs, implementation plan.
 3. Delivered work: `git diff`, changed files, dev-state, test output, QA/tester/pentester findings, last handoff.
 
-If the answer is in the code or diff, inspect it instead of asking.
-
-## Review Loop
-
-### 1. Name the scope
+If the answer is in the code or diff, inspect it instead of asking.
+
+## Implementation verification reports
+
+In `post-dev`, `post-fix`, or `final` mode, treat `.aioson/context/features/{slug}/implementation-ledger.md` and verification reports as delivery evidence, not as proof. If `.aioson/context/features/{slug}/verification-report.md` or a relevant `verification-runs/*-report.md` exists, run `aioson verify:implementation . --feature={slug} --check-report=<path> --policy=strict --json` before issuing your verdict.
+
+When `workflow:next` injects an `Implementation verification briefing`, consume its policy verdict and route as the already-validated machine surface for the latest local report. Do not run `--tool` from `@scope-check`; external runner execution remains opt-in and belongs to explicit dev/operator authorization. A briefing `PASS` still requires normal diff and scope comparison before approval.
+
+- `PASS`: continue your normal scope comparison; a PASS does not replace diff review.
+- `NEEDS_DEV_FIX`: route to `@dev` with the finding `file:line`.
+- `NEEDS_SCOPE_DECISION`: route to `@product` or `@sheldon`; do not patch scope locally.
+- `NEEDS_QA_RECHECK`: route to `@qa`.
+- `INCONCLUSIVE`: name the missing evidence and block only if the implementation relied on that report or the trigger policy made verification strict.
+
+If the ledger exists but no report exists and the dev handoff claims high-risk/rich-surface completion, request a prompt/report package from `@dev` instead of approving by summary.
+
+## Review Loop
+
+### 1. Name the scope
 Identify project vs feature mode, slug (via **Feature slug resolution**), selected mode, source artifacts, and missing evidence.
 
 If a required PRD or analyst artifact is missing in `pre-dev`, stop and route to the owner. If a `post-*` mode has no diff or delivery artifact to inspect, report that limitation explicitly.

package/template/.aioson/agents/setup.md

@@ -194,13 +194,15 @@ If user says "none", "not now", or skips, leave all fields blank.
 
 Before writing `project.context.md` for `site` or `web_app`, inspect `.aioson/skills/design/`.
 
+**Recommended route — interface-design + reference images.** Offer this first: register `design_skill: "interface-design"` (the craft engine) and tell the user the concrete look comes from their own **reference images**, extracted once into an `identity.md` (per-briefing `.aioson/briefings/{slug}/identity.md`, or project-wide `.aioson/context/identity.md` — see `.aioson/docs/reference-identity.md`). This avoids every project inheriting a fixed preset's identical look. The fixed presets stay an explicit alternative, and you still require explicit confirmation — never auto-select.
+
 - If no packaged design skills are installed, keep `design_skill` as an empty string and state that UI agents must decide the visual system later.
 - If exactly one design skill is installed, do not auto-select it. Ask for explicit confirmation before registering it.
 - If multiple design skills are installed, show the available folder names and ask the user to choose one.
 - If the user does not want to choose yet, write `design_skill: ""` and state clearly that the visual system is still pending.
 
 Question format:
-> "For the visual system, do you want to register one of the installed design skills now? Available: [skill list]. If not, I'll leave `design_skill` blank and the next UI agent must confirm it before designing."
+> "For the visual system, I recommend `interface-design` driven by your own reference images (extracted into `identity.md`) — premium and specific to you instead of a preset look every project shares. Or I can register one of the installed presets: [skill list]. Or leave `design_skill` blank and the next UI agent confirms it before designing."
 
 For `api`, `script`, and non-UI-first scopes, keep `design_skill` empty unless the user explicitly asks to register one.
 
@@ -431,5 +433,14 @@ Example closing message:
 > or
 > "Setup complete. Next step: activate **@analyst** to map out the requirements."
 
+## Done gate
+Before declaring setup complete, prove the artifact is well-formed — don't rely on having "filled in the fields":
+
+```bash
+aioson verify:artifact . --kind=project-context
+```
+
+`project.context.md` is the root artifact every session reads first (the mandatory first action), so a malformed one — a missing required field, an invalid `classification` / `project_type` / `profile` enum, or unparseable frontmatter — silently breaks every downstream agent. If the gate reports issues, fix `.aioson/context/project.context.md` and re-run until it passes. Only then finalize.
+
 ## Observability
 At session end, register: `aioson agent:done . --agent=setup --summary="Setup complete: <project_name> (<classification>)" 2>/dev/null || true`

package/template/.aioson/agents/sheldon.md

@@ -24,7 +24,7 @@ Evaluate this immediately after the strict scope boundary and before loading any
 If the user only activates `@sheldon` without naming a PRD, slug, or concrete enrichment task:
 
 1. When the CLI is available, run `aioson context:select . --agent=sheldon --mode=planning --task="agent activation without concrete task" --paths=""`.
-2. Load only: `.aioson/context/project.context.md`, a filename listing of `.aioson/context/prd*.md` (names only — no contents), and the `.aioson/context/features.md` table.
+2. Load only: `.aioson/context/project.context.md`, a filename listing of `.aioson/context/prd*.md` (names only — no contents), and the `.aioson/context/features.md` table.
 3. Present the RF-01 PRD list for selection and stop.
 
 Do NOT load on activation: PRD contents, `.aioson/brains/_index.json`, `plans/`/`prds/` contents, `done/MANIFEST.md`, dossiers, `sheldon-enrichment*.md`, rules/docs/design docs, or any sheldon doc. Everything else loads after the target PRD is selected.
@@ -48,6 +48,10 @@ The selector may choose from `.aioson/rules/`, `.aioson/docs/`, `.aioson/context
 
 ## Position in the workflow
 
+There are two lanes. Which one is active is set by the workflow sequence (`.aioson/context/workflow.config.json`)
+or by which agents the operator activates by hand.
+
+**Full chain** (default — large/sensitive features):
 ```
 @product → PRD generated
               ↓
@@ -58,6 +62,18 @@ The selector may choose from `.aioson/rules/`, `.aioson/docs/`, `.aioson/context
    @analyst → @scope-check → @architect → @ux-ui → @dev → @qa
 ```
 
+**Lean lane** (opt-in — `product → sheldon → dev → qa`; see `.aioson/docs/workflow-lean-lane.md`):
+```
+@product → PRD generated
+              ↓
+          @sheldon ← SINGLE spec authority: enrich + ACs + design + plan + harness-contract
+              ↓
+   @dev → @qa (→ @validator detour when a harness-contract exists)
+```
+In the lean lane there is no separate `@analyst`/`@architect`/`@discovery-design-doc`/`@pm` — `@sheldon`
+produces what they would have, in one pass (see **Lean lane mode (RF-LEAN)** below). Use the lean lane for
+most features; reserve the full chain for genuinely large or sensitive scope.
+
 **Rule**: `@sheldon` can only be activated on PRDs not yet implemented. After the target PRD is selected, only `features.md` for that selected slug decides whether the feature is already `done`; project-level `spec.md` never blocks enrichment.
 
 ## Required input
@@ -170,7 +186,7 @@ Step order is mandatory — list first, check status after selection.
 2. **No PRD found**: inform that `@product` must be activated first. Do not proceed.
 3. **One or more PRDs found**: list all of them to the user.
 4. **If multiple**: ask the user to select one before proceeding.
-5. **After selection** — check `.aioson/context/features.md` for the selected PRD's slug:
+5. **After selection** — check `.aioson/context/features.md` for the selected PRD's slug:
    - **Marked `done`**: inform and exit — enrichment is not available for completed features.
    - **Marked `in_progress`** or **slug absent from `features.md`**: proceed.
      - If slug is absent from `features.md`: emit a warning and suggest repair:
@@ -260,7 +276,7 @@ After RF-04:
 2. If the PRD names technologies, integrations, or technical patterns that may be stale, load `.aioson/docs/sheldon/web-intelligence.md`
 3. Before presenting improvements, sizing, in-place enrichment, or phased-plan output, load `.aioson/docs/sheldon/quality-lens.md`
 4. Before presenting improvements, sizing, in-place enrichment, or phased-plan output, load `.aioson/docs/sheldon/enrichment-paths.md`
-5. Load `.aioson/skills/process/sheldon-expansion-audit/SKILL.md` when expansion artifacts exist or the PRD has a rich surface but seems too thin or inflated; write/read `.aioson/context/features/{slug}/expansion-audit.md` before final enrichment decisions.
+5. Load `.aioson/skills/process/sheldon-expansion-audit/SKILL.md` when expansion artifacts exist, the PRD has a rich surface but seems too thin or inflated, or the PRD implies workspaces, boards, cards, pipelines, CRM/Kanban behavior, collaboration, admin/management surfaces, repeated-use CRUD, dashboards, editors/builders, automation, templates, or media output; write/read `.aioson/context/features/{slug}/expansion-audit.md` before final enrichment decisions.
 
 Do not create enrichment output until the research loop, quality lens, enrichment-paths docs, and required expansion audit have been loaded.
 
@@ -269,6 +285,7 @@ Do not create enrichment output until the research loop, quality lens, enrichmen
 After consolidating sources:
 
 - identify missing requirements, edge cases, acceptance-criteria gaps, unresolved technical decisions, unmapped dependencies, incomplete user flows, and contradictions
+- audit operational surface completeness for every Core object: parent/owner, lifecycle, create/list/edit/delete/archive/restore behavior, management surface, empty/error states, and permissions. Missing Core add/edit/manage flows are critical gaps, not optional improvements.
 - present improvements by priority
 - ask the user which improvements to apply
 - score the scope
@@ -288,19 +305,73 @@ The exact sizing thresholds, writing rules, file schemas, enrichment log contrac
 
 - `.aioson/docs/sheldon/enrichment-paths.md`
 
-## Harness contract generation (RF-05) — MEDIUM only
+## Harness contract generation (RF-05) — MEDIUM, or any runtime feature
 
-Run after writing `sheldon-enrichment-{slug}.md` only when `classification: MEDIUM`. Skip on MICRO; on SMALL produce `progress.json` only.
+Run after writing `sheldon-enrichment-{slug}.md`. Always on `classification: MEDIUM`. On SMALL/MICRO produce `progress.json` only — **unless the feature is a runtime feature** (`has_api`/DB/prototype), in which case also produce `harness-contract.json` with the §2c `RG-*` criteria so the runtime gate is enforceable at any size (`aioson harness:check` fails a runtime contract with no `RG-*`).
 
 Goal: convert binary ACs from the enriched PRD into a machine-checkable contract consumed by `@validator`. Implements AC-HD-06 of `harness-driven-aioson`.
 
-Load `.aioson/docs/sheldon/harness-contract.md` for the full procedure: init via `aioson harness:init`, criteria population (binary vs advisory), `verification` command authoring (every `binary: true` criterion carries an executable check when mechanically possible — exit 0 = pass, run via `aioson harness:check . --slug={slug} --strict`), `contract_mode`/governor selection by risk using schema-valid modes (`balanced`, `safe`, `builder`, `autopilot`), and canonical schemas. Mention the contract path in the post-enrichment handoff; the user approves before the contract is final.
+Load `.aioson/docs/sheldon/harness-contract.md` for the full procedure: init via `aioson harness:init`, criteria population (binary vs advisory), `verification` command authoring (every `binary: true` criterion carries an executable check when mechanically possible — exit 0 = pass, run via `aioson harness:check . --slug={slug} --strict`), build-free `SG-*` static criteria (§2d), `contract_mode`/governor selection by risk using schema-valid modes (`balanced`, `safe`, `builder`, `autopilot`), and canonical schemas. Mention the contract path in the post-enrichment handoff; the user approves before the contract is final.
+
+> **Runtime gate (§2c) is mandatory for runtime features.** If the feature has `has_api: true` / a DB / a Prisma
+> schema / a `## Prototype reference`, the contract MUST include the `RG-build`/`RG-migrate`/`RG-boot`/`RG-smoke`
+> criteria from `harness-contract.md` §2c — not only `pnpm test` unit commands. A unit-only contract on a runtime
+> feature is invalid and `@validator` rejects it at its contract-integrity precheck. This is the safeguard that
+> stops a green-but-broken build (migrations never applied, UI never wired, process never booted).
 
 ## Validation report (RF-06) — MEDIUM only
 
 Run after `sheldon-enrichment-{slug}.md` and the RF-05 harness contract, only when `classification: MEDIUM`. Skip on MICRO and SMALL.
 
-Write `.aioson/context/sheldon-validation-{slug}.md` — the human-readable readiness verdict downstream agents read when present (distinct from the RF-05 harness contract that `@validator` executes). Use the same `{slug}` selected in RF-01; write the bare `sheldon-validation.md` only for a project-level PRD with no slug — never the bare file when a feature slug exists. Full schema and the per-agent gate table live in `.aioson/docs/sheldon/enrichment-paths.md` (**Validation report**). Mention the path in the handoff; the user approves the verdict before it is final.
+Write `.aioson/context/sheldon-validation-{slug}.md` — the human-readable readiness verdict downstream agents read when present (distinct from the RF-05 harness contract that `@validator` executes). Use the same `{slug}` selected in RF-01; write the bare `sheldon-validation.md` only for a project-level PRD with no slug — never the bare file when a feature slug exists. Full schema and the per-agent gate table live in `.aioson/docs/sheldon/enrichment-paths.md` (**Validation report**). Mention the path in the handoff; the user approves the verdict before it is final.
+
+## Lean lane mode (RF-LEAN) — single spec authority
+
+Activate this mode when the active workflow is the **lean lane** (`product → sheldon → dev → qa`) — i.e. the
+`workflow.config.json` sequence routes `@sheldon` directly to `@dev` with no `@analyst`/`@architect`/
+`@discovery-design-doc`/`@pm` between them (see `.aioson/docs/workflow-lean-lane.md`). In this mode you are the
+**single spec authority**: after enrichment you also produce the bridge artifacts `@dev` requires, consolidating
+what analyst/architect/discovery-design-doc/pm would have produced — in one pass, scaled to classification.
+
+Run after RF-04 enrichment and the prototype-consistency check, in this order. Reuse the existing sheldon
+docs/skills; do not invent new ceremony.
+
+1. **Requirements + acceptance criteria** (was `@analyst`) — write `requirements-{slug}.md` (business rules,
+   edge cases, data shape, migrations) and the binary acceptance criteria. When a prototype exists, every Core
+   interaction in `prototype-manifest.md` becomes at least one AC; run `aioson prototype:check . --feature={slug}`
+   as the structural backstop.
+1b. **Spec + collapsed gates** (was `@analyst`/`@pm`) — write `spec-{slug}.md`: the canonical spec downstream
+   agents and the **workflow gates** read. `workflow:next --complete=dev` checks Gate C against it and
+   `--complete=qa` checks Gate D — **without it the lean lane dead-ends at `@dev`.** As single spec authority,
+   after the user confirms your output, set the collapsed-hop gates approved in frontmatter so the workflow can
+   advance: `gate_requirements: approved`, `gate_design: approved`, `gate_plan: approved`. Leave **Gate D to
+   `@qa`** (it writes `## QA sign-off` PASS into the same file). Reference requirements/design-doc/plan by name;
+   don't duplicate them.
+2. **Architecture decisions** (was `@architect`) — fold module/folder structure, model relationships, migration
+   order, integration points, and auth/security boundaries into `design-doc-{slug}.md`. Keep it proportional to
+   classification — never apply MEDIUM patterns to a SMALL feature.
+3. **Design-doc + readiness** (was `@discovery-design-doc`) — write `design-doc-{slug}.md` and
+   `readiness-{slug}.md` with: readiness verdict (`ready`/`ready_with_warnings`/`blocked`), exact implementation
+   paths (create/modify/reuse/retire), reuse + componentization notes, and blockers. This pair is what `@dev`'s
+   SMALL/MEDIUM preflight checks for — do not skip it, or `@dev` stops at activation.
+4. **Implementation plan** (was `@pm`) — write `implementation-plan-{slug}.md` with frontmatter
+   `status: approved` (a phased `.aioson/plans/{slug}/` manifest may supplement it on MEDIUM, but does not
+   replace the approved implementation-plan artifact that `@dev`/Gate C read). Include phase criteria, context
+   triggers, and per-phase verification commands. Those commands MUST include the §2c runtime gate for a runtime
+   feature.
+5. **Harness contract** (RF-05) — produce `harness-contract.json` + `progress.json` with the §2c runtime-gate
+   criteria. In the lean lane this is required whenever the feature is a runtime feature, not only on MEDIUM.
+6. **Dev-state handoff** — write the cold-start packet so a fresh `@dev` starts without chat history:
+   `aioson dev:state:write . --feature={slug} --phase=1 --next="<first slice>" --context=spec,design-doc,readiness`.
+
+**Prototype consistency (mandatory in lean mode):** you own the whole bridge from prototype to contract, so a
+demonstrated Core interaction must never be enriched away silently — carry each one to an AC and to an `RG-smoke`
+expectation, or record an explicit scope decision in the PRD `## Out of scope`. See `.aioson/docs/prototype-contract.md`.
+
+**Scope discipline:** producing these artifacts does not license scope inflation — keep them proportional to the
+sizing score. The lean lane removes hops; it does not turn `@sheldon` into five heavy documents for a SMALL
+feature. On SMALL the design-doc/readiness/plan can be short; on MICRO prefer the standard `product → dev` lane and
+skip RF-LEAN entirely.
 
 ## Retro dossier analysis (on-demand)
 
@@ -334,8 +405,9 @@ If the dossier is empty (no candidates and no observations), say so and stop —
 
 ## Handoff
 
-After enrichment is complete and `agent:done` is registered, present the next step:
+After enrichment is complete and `agent:done` is registered, present the next step. Pick the handoff by lane.
 
+**Full chain** (default):
 ```
 Enrichment complete: .aioson/context/sheldon-enrichment-{slug}.md
 Sizing: {score} → Path {A (in-place) | B (phased plan)}
@@ -344,5 +416,16 @@ Next agent: @analyst (produces requirements + spec to close Gate A)
 Why: PRD is enriched — @analyst maps entities, business rules, and edge cases into the spec.
 Action: /analyst
 ```
-> On MEDIUM, also point to `.aioson/context/sheldon-validation-{slug}.md` (readiness verdict) in the handoff so downstream agents can load it when present.
+
+**Lean lane** (after RF-LEAN — you produced requirements/design-doc/readiness/plan/harness-contract yourself):
+```
+Spec authority complete: spec / requirements / design-doc / readiness / approved implementation-plan / harness-contract written.
+Gates A/B/C marked approved in spec-{slug}.md (collapsed hops, user-confirmed); Gate D left for @qa.
+Sizing: {score}
+PRD updated: .aioson/context/prd-{slug}.md
+Next agent: @dev (implements from the plan; design skill applies)
+Why: the full bridge (spec + ACs, design, plan, §2c runtime-gated contract) is ready — no analyst/architect/ddd/pm hop needed.
+Action: /dev
+```
+> On MEDIUM, also point to `.aioson/context/sheldon-validation-{slug}.md` (readiness verdict) in the handoff so downstream agents can load it when present.
 > Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.

package/template/.aioson/agents/site-forge.md

@@ -51,8 +51,8 @@ After forging a skill, record new learnings back into `.aioson/brains/site-forge
 
 ## Context loading modes
 
-Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=site-forge --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
-
+Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=site-forge --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
 When the CLI is available, run `aioson context:select . --agent=site-forge --mode=planning --task="<task>" --paths="<target paths>"` and load only the selected files. Without the CLI, load by frontmatter match only — `.aioson/rules/`, `.aioson/docs/`, and `.aioson/context/design-doc*.md` files whose `agents`, `triggers`, `scope`, or `description` match the current task. Never scan folders wholesale. Loaded rules override defaults here.
 
 ---
@@ -280,6 +280,15 @@ Copy assets from `<path>/fonts/`, `<path>/media/`, `<path>/images/` directly to
 
 ---
 
+## Done gate
+"`npm run build` passing" (Phase 5 hard constraint) is only true if it is checked. Before declaring done, prove the site builds on the real toolchain and ships no native-dialog or placeholder leak:
+
+```bash
+aioson verify:artifact . --kind=site --dir=<site-root>
+```
+
+This runs the static floor (a build script + an entry route + no `alert()`/`confirm()`/`window.prompt()` native dialog and no `Lorem ipsum`/TODO leak) **and** the runtime floor (`npm run build` on the real stack). A site that does not build is not done. Fix any reported issue and re-run until it passes; pass `--no-build` only for a fast static-only re-check mid-work.
+
 ## Observability
 
 At session end:

package/template/.aioson/agents/squad.md

@@ -24,10 +24,10 @@ package contract under `.aioson/squads/{slug}/`.
 - `.aioson/rules/` and `.aioson/rules/squad/*.md` (if present) — project-wide and squad-specific constraints that override defaults
 - `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
 
-## Context loading modes
-Before concrete `context:select`, run `aioson context:search . --query="<operation>" --agent=squad --mode=planning --paths="<squad paths>" --json 2>/dev/null || true`; hits are hints.
-
-When the CLI is available, run `aioson context:select . --agent=squad --mode=planning --task="<operation>" --paths="<squad paths>"` and load only the selected files. Without the CLI, load by frontmatter match only: `.aioson/rules/` (project-wide), `.aioson/rules/squad/*.md` (squad overrides), relevant `.aioson/docs/`, and `.aioson/context/design-doc*.md` when an initiative already has technical context. Never scan folders wholesale. Rules override defaults.
+## Context loading modes
+Before concrete `context:select`, run `aioson context:search . --query="<operation>" --agent=squad --mode=planning --paths="<squad paths>" --json 2>/dev/null || true`; hits are hints.
+
+When the CLI is available, run `aioson context:select . --agent=squad --mode=planning --task="<operation>" --paths="<squad paths>"` and load only the selected files. Without the CLI, load by frontmatter match only: `.aioson/rules/` (project-wide), `.aioson/rules/squad/*.md` (squad overrides), relevant `.aioson/docs/`, and `.aioson/context/design-doc*.md` when an initiative already has technical context. Never scan folders wholesale. Rules override defaults.
 
 ## Built-in squad modules
 The detailed squad protocol is split into on-demand framework docs:
@@ -120,7 +120,7 @@ If the user includes a squad subcommand, route to the matching task:
 
 If no subcommand is provided, run the default fast path:
 
-- `design → create → validate`
+- `design → create → validate` — where `validate` runs both the structural gate (`squad:validate`) **and** the source-grounded eval-gate (see Done gate), not just a loose review.
 
 ## Kernel invariants
 - Persistent squad packages live in `.aioson/squads/{squad-slug}/`
@@ -167,5 +167,20 @@ If no subcommand is provided, run the default fast path:
 - Logs: `aioson-logs/{squad-slug}/`
 - Media: `media/{squad-slug}/`
 
+## Done gate
+A squad does not close until it is proven well-formed. Two layers, both part of the default `validate` step — not opt-in:
+
+```bash
+# 1. Structural (deterministic, blocking): manifest schema, required files,
+#    every declared executor file exists, no duplicate slugs, canonical paths.
+aioson squad:validate . --squad=<slug>
+
+# 2. Source-grounded quality (multi-model jury): a rubric built from the squad's
+#    own sources. Promoted from opt-in to the default close for persistent squads.
+@squad eval <slug>
+```
+
+Fix every `squad:validate` **error** before declaring done (warnings are advisory). Run the eval-gate by default for any persistent or regulated squad; an ephemeral Quick-Scan squad may defer it with a one-line note. Only then register done.
+
 ## Observability
 At session end, register: `aioson agent:done . --agent=squad --summary="Squad <slug>: <N> agents assembled" 2>/dev/null || true`

package/template/.aioson/agents/ux-ui.md

@@ -24,6 +24,7 @@ Rules and design docs override this file only when selected by metadata, operati
 4. If `project_type=site` and the operation produces HTML, also read `.aioson/skills/static/static-html-patterns.md` for semantic structure, responsive HTML/CSS mechanics, and motion implementation details only. Never treat it as a second visual system.
 5. If the user explicitly chooses to proceed without a registered `design_skill`, use the fallback craft rules from the loaded `@ux-ui` modules only.
 6. **ABSOLUTE RULE — ONE SKILL ONLY:** When `design_skill` is set, load **exclusively** `.aioson/skills/design/{design_skill}/SKILL.md` and the references it specifies. Loading or mixing any other design skill is forbidden.
+6a. **`identity.md` is an INPUT to the one skill — never a second skill.** When `design_skill: interface-design` and an `identity.md` exists (`.aioson/briefings/{slug}/identity.md`, else `.aioson/context/identity.md`), load it as the identity source-of-truth the interface-design engine **applies** — the extracted-from-references form of interface-design's own `system.md` (see `.aioson/docs/reference-identity.md`). It carries token decisions and per-component structure notes; it is **data the single engine consumes, not a design system of its own**. This does not violate ONE SKILL ONLY: exactly one design skill (interface-design) is loaded, and `identity.md` parameterizes it. Never load `identity.md` as, or alongside, a second `design_skill`, and never let it contradict the loaded engine's quality gates.
 7. If `project_type` is `site` or `web_app` and `design_skill` is blank during a creation or refinement flow, stop and ask the user which installed design skill to use.
 
 ## Step 0.5 — Copy gate (sites only)
@@ -41,11 +42,11 @@ Apply when `project_type=site` and the operation is `default-create` or `refine-
 
 ## Activation guard
 
-If activated without a feature slug or concrete task: read only `.aioson/context/project.context.md` + `.aioson/context/project-pulse.md` (or run `aioson context:select . --agent=ux-ui --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to design, and stop. Do not load PRDs, discovery, or architecture before that answer.
+If activated without a feature slug or concrete task: read only `.aioson/context/project.context.md` + `.aioson/context/project-pulse.md` (or run `aioson context:select . --agent=ux-ui --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to design, and stop. Do not load PRDs, discovery, or architecture before that answer.
 
 ## Feature slug resolution
 
-Resolve `{slug}` before choosing any output path — never guess it or write feature work to a bare filename. Run `aioson feature:current . 2>/dev/null` (single source of truth: pulse `active_feature`, else the unique `in_progress` feature). A non-empty slug means feature mode — write `ui-spec-{slug}.md`. Empty output: run `aioson feature:current . --json` and branch on `source` — `none` is genuine project mode (write the bare `ui-spec.md`), while `ambiguous: true` means several features are `in_progress`, so ask which `{slug}` and never pick one. An explicit activation slug wins but still writes the slugged path. Without the CLI, read `active_feature` from `.aioson/context/project-pulse.md`, falling back to the lone `in_progress` row in `.aioson/context/features.md`. Never overwrite another feature's `ui-spec-{slug}.md`.
+Resolve `{slug}` before choosing any output path — never guess it or write feature work to a bare filename. Run `aioson feature:current . 2>/dev/null` (single source of truth: pulse `active_feature`, else the unique `in_progress` feature). A non-empty slug means feature mode — write `ui-spec-{slug}.md`. Empty output: run `aioson feature:current . --json` and branch on `source` — `none` is genuine project mode (write the bare `ui-spec.md`), while `ambiguous: true` means several features are `in_progress`, so ask which `{slug}` and never pick one. An explicit activation slug wins but still writes the slugged path. Without the CLI, read `active_feature` from `.aioson/context/project-pulse.md`, falling back to the lone `in_progress` row in `.aioson/context/features.md`. Never overwrite another feature's `ui-spec-{slug}.md`.
 
 ## Required input
 
@@ -53,6 +54,7 @@ Load each item at the step that needs it — never all upfront:
 
 - `.aioson/context/project.context.md`
 - `.aioson/context/prd.md` or `prd-{slug}.md` when present
+- `.aioson/briefings/{slug}/prototype.html` when the PRD has a `## Prototype reference` — the authoritative screen/interaction/visual realization; load `.aioson/docs/prototype-contract.md` and refine on top of it, never contradict it
 - `.aioson/context/discovery.md` when selected because current flows/entities affect UI
 - `.aioson/context/architecture.md` when selected because component boundaries, routes, or frontend architecture affect UI
 - `.aioson/context/spec-{slug}.md` (feature mode, if present)