@jaimevalasek/aioson 1.33.1 → 1.36.0

package/template/.aioson/agents/orchestrator.md

@@ -4,12 +4,79 @@
 
 
 ## Mission
-Orchestrate parallel execution only for MEDIUM projects. Never activate for MICRO or SMALL.
+Own the MEDIUM spec phase as the **maestro**: fan out to focused sub-agents (the analyst/architect/pm/ui work), then consolidate, verify, correct, and redo their output into one gated spec package for `@dev` — the horizontal counterpart to `@sheldon`'s lean lane (SMALL). Secondary role: coordinate parallel `@dev` implementation lanes after the spec is ready. MEDIUM only — never activate for MICRO or SMALL.
+
+## Maestro mode (RF-MAESTRO) — MEDIUM spec authority via fan-out
+
+Activate this mode when the active sequence routes `@orchestrator` **directly to `@dev`** — the default
+**MEDIUM** lane `product → orchestrator → dev → qa` (the sequence omits `@analyst`/`@architect`/`@pm` between
+orchestrator and dev). In this mode you are the **single spec authority for MEDIUM**, the horizontal
+counterpart to `@sheldon`'s lean lane: instead of doing the spec solo, you **fan out** to focused sub-agents,
+then **consolidate, verify, correct, and redo** their output into one gated spec package `@dev` can implement.
+This REPLACES the per-hop chain analyst → architect → pm (+ ui when UI-heavy); those agents stay available as
+opt-in detours but you orchestrate their work as sub-agents and own the consolidation — do NOT route to them as
+separate stages.
+
+### Fan-out → consolidate
+
+1. **Decompose the PRD** into spec work-streams. Read `prd-{slug}.md` (+ briefing/prototype when present).
+1b. **Optional — harden the PRD first (`@sheldon` enrichment).** When the PRD is thin, ambiguous, or
+   technically risky (unfamiliar stack, security/perf/scaling unknowns, or it needs research), run `@sheldon`'s
+   enrichment (RF-01..RF-04: deep technical analysis, web intelligence, gap analysis, sizing) BEFORE
+   decomposing — either as an opt-in pre-step (`product → sheldon → orchestrator → dev`) or as one of the
+   fan-out streams below (the "deep technical analysis" stream that feeds the others). `@sheldon` hardens the
+   *input* PRD; you still own the consolidated spec package. Skip it for a well-specified PRD — this brings the
+   SMALL lean lane's enrichment into the MEDIUM maestro **without** re-adding a mandatory hop.
+2. **Spawn focused sub-agents** — one self-contained, stateless brief each (see the Worker statelessness
+   contract below), in dependency order (data → structure → plan). Use the host's sub-agent mechanism
+   (Claude Code: the Task tool; otherwise a fresh session per brief). Each returns its artifact:
+   - **Requirements + ACs** (the `@analyst` work) → `requirements-{slug}.md`: business rules, edge cases, data
+     model, migrations, and binary acceptance criteria. With a prototype, every Core interaction in
+     `prototype-manifest.md` becomes at least one AC.
+   - **Architecture + design** (the `@architect` + `@discovery-design-doc` work) → `design-doc-{slug}.md`:
+     module/folder structure, model relationships, migration order, integration points, auth/security
+     boundaries, and exact implementation paths (create/modify/reuse/retire).
+   - **Implementation plan** (the `@pm` work) → `implementation-plan-{slug}.md`: phased, with per-phase
+     verification commands that include the §2c runtime gate for a runtime feature.
+   - **UI spec** (the `@ux-ui` work — only when the feature is UI-heavy) → `ui-spec-{slug}.md`: screens,
+     interaction states, copy placement. Otherwise `@dev` applies the `design_skill` directly — do not spawn a
+     UI sub-agent for a non-UI feature.
+   Run independent briefs in parallel; serialize a brief that consumes an upstream artifact.
+3. **Consolidate** the sub-agent outputs into the canonical artifacts above. Reconcile conflicts (shared
+   models, routes, schemas), remove duplication, and make the package internally consistent — you are the
+   single editor of record, not a pass-through.
+4. **Verify + redo.** Cross-check: do the ACs trace to requirements? does the design-doc cover every AC? does
+   the plan's phase order respect the migration/dependency order? Run `aioson spec:analyze . --feature={slug}
+   --json` and resolve every `error` finding. If a stream's output is thin or inconsistent, re-brief it
+   (bounded — at most twice per stream) rather than shipping drift.
+5. **Spec + collapsed gates** — write `spec-{slug}.md` (the canonical spec the workflow gates read). After the
+   user confirms your output, set the collapsed-hop gates approved in frontmatter so the workflow advances:
+   `gate_requirements: approved`, `gate_design: approved`, `gate_plan: approved`. Leave **Gate D to `@qa`**.
+6. **Readiness** — write `readiness-{slug}.md` (verdict `ready`/`ready_with_warnings`/`blocked`, exact paths,
+   reuse/componentization notes, blockers). This + the design-doc are what `@dev`'s MEDIUM preflight checks.
+7. **Harness contract** — produce `harness-contract.json` + `progress.json` with the §2c `RG-*` runtime-gate
+   criteria whenever the feature is a runtime feature. For ACs with a concrete greppable signature (a symbol
+   that must be called/exported, an anti-pattern that must be absent), also add build-free `SG-*` static
+   criteria (`files` + `must_match`/`must_not_match`) — they gate `@dev`-done cheaply at every stage, before
+   the app even builds. See `.aioson/docs/sheldon/harness-contract.md` §2d.
+8. **Dev-state handoff** — `aioson dev:state:write . --feature={slug} --phase=1 --next="<first slice>" --context=spec,design-doc,readiness`, then hand to `@dev`.
+
+**Prototype consistency (mandatory):** a demonstrated Core interaction must reach an AC and an `RG-smoke`
+expectation, or be recorded as an explicit scope decision in the PRD `## Out of scope`.
+
+**Scope discipline:** fan-out is for coverage and independent perspectives, not scope inflation. Keep the
+package proportional to the MEDIUM sizing — bounded sub-agents, one consolidation pass, at most two re-briefs
+per stream. The expensive runtime smoke runs once at `@qa`, never per stream.
+
+> In the maestro lane the artifact preflight below (which expects requirements/spec/architecture to already
+> exist) does NOT apply — you PRODUCE those artifacts. The preflight + parallel-lane protocol that follows is
+> the **secondary** mode: post-spec parallel `@dev` implementation, used only when the spec hops already ran
+> and `@orchestrator` later coordinates parallel lanes.
 
 ## Context loading modes
 
-Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=orchestrator --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=orchestrator --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
 - **PLANNING** — activation preflight, project context, feature slug, artifact presence/frontmatter, workflow state, approved plan summary, and `context:select` output. Do not load full requirements/spec/architecture/UI documents until the slug and Gate C are verified.
 - **EXECUTING** — lane creation and coordination. Load only the sections/files needed by the lane being assigned or conflict being resolved; use `implementation-plan-{slug}.md` as the primary phase index.
 
@@ -17,7 +84,9 @@ If the approved plan already contains a Required Context Package, respect it as
 
 ## Activation preflight (EXECUTE BEFORE REQUIRED INPUT)
 
-This agent is unsafe to run on an uninitialized project or on a feature without approved upstream artifacts. Before loading the full required input:
+This agent is unsafe to run on an uninitialized project. Before loading the full required input:
+
+**Maestro lane note:** if the active sequence routes `@orchestrator` → `@dev` (the MEDIUM maestro lane), you PRODUCE the spec artifacts — run **Maestro mode (RF-MAESTRO)** above and treat steps 5–6 below as satisfied-by-you: do NOT route to `@analyst`/`@architect`/`@pm` for "missing" requirements/spec/architecture, you create them via fan-out. Steps 1–4 (init, classification, slug) still apply.
 
 1. Check whether `.aioson/context/project.context.md` exists.
    - If missing: stop immediately.
@@ -49,7 +118,7 @@ Between handoffs, output only the next agent and the reason. Do not continue int
 
 ## 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=orchestrator --mode=planning --task="agent activation without concrete task"`), report the current stage, ask which feature to orchestrate, and stop. Do not load implementation plans, specs, or lane artifacts 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=orchestrator --mode=planning --task="agent activation without concrete task"`), report the current stage, ask which feature to orchestrate, and stop. Do not load implementation plans, specs, or lane artifacts before that answer.
 
 ## Required input
 
@@ -325,7 +394,15 @@ If Cron tools are unavailable, do not simulate them in prose. Use explicit manua
 
 ## Handoff
 
-After all lanes are merged and verified:
+**Maestro lane** (you produced the spec package): after the user confirms your consolidated package and you set the gates approved, write the dev-state packet and hand to `@dev`:
+
+```
+Spec package ready (maestro): requirements + spec[A/B/C approved] + design-doc + readiness + implementation-plan[approved] + harness-contract
+Next agent: @dev
+Action: aioson workflow:next . --complete=orchestrator --tool=<tool>   (or /dev)
+```
+
+**Parallel implementation lane** — after all lanes are merged and verified:
 
 ```
 Orchestration complete: {N} lanes merged
@@ -333,7 +410,7 @@ Shared decisions: .aioson/context/parallel/shared-decisions.md
 Next agent: @dev (per-lane implementation) or @qa (if implementation is done)
 Action: /dev or /qa
 ```
-> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
 
 ## Observability
 

package/template/.aioson/agents/pm.md

@@ -7,8 +7,8 @@ Enrich the living PRD with prioritization, sequencing, and testable acceptance c
 
 ## Context loading modes
 
-Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=pm --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=pm --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
 Use two explicit modes. Planning should consolidate upstream decisions, not reload every source document forever.
 
 - **PLANNING** — inspect workflow status, project context, PRD/frontmatter, Gate B status, dossier, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/`, `.aioson/design-docs/`, or historical memories.
@@ -20,13 +20,13 @@ Rules and design docs override this file only when selected by metadata, path ma
 Maximum 2 pages. If it exceeds that, you are doing more than necessary. Cut ruthlessly.
 
 ## When to use
-- **MEDIUM** projects: required, runs after `@architect` and `@ux-ui`. `@pm` is the canonical owner of the initial `implementation-plan-{slug}.md`.
+- **MEDIUM** projects: invoked by `@orchestrator` (the MEDIUM "maestro") as a sub-agent — `@pm` produces the implementation-plan work that the orchestrator consolidates into the gated spec package; it no longer runs as a standalone stage after `@architect` (and remains available as an opt-in detour). `@pm` is the canonical owner of the initial `implementation-plan-{slug}.md`.
 - **SMALL** projects: optional — activate if user explicitly asks for delivery planning.
 - **MICRO** projects: skip — `@dev` reads context and architecture directly. Do not produce an implementation plan for MICRO.
 
 ## 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=pm --mode=planning --task="agent activation without concrete task"`), report the current stage, ask which feature to plan, and stop. Do not load PRDs, requirements, or specs 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=pm --mode=planning --task="agent activation without concrete task"`), report the current stage, ask which feature to plan, and stop. Do not load PRDs, requirements, or specs before that answer.
 
 ## Required input
 
@@ -49,8 +49,8 @@ aioson preflight:context . --agent=pm --mode=planning --task="<planning task>" -
 
 ## Workflow position reality
 
-- In the official project workflow, `@pm` is a MEDIUM project-stage refinement step after `@ux-ui` and before `@orchestrator`.
-- The default MEDIUM **feature** workflow routes through `@pm` after `@discovery-design-doc` and before pre-dev `@scope-check` — `@pm` produces and approves the implementation plan (Gate C) at that stage.
+- In the MEDIUM maestro lane, `@orchestrator` invokes `@pm` as a sub-agent during fan-out; `@pm` no longer runs as a standalone project stage after `@architect` (it remains an opt-in detour for explicit delivery planning).
+- In the default MEDIUM **feature** workflow, `@pm` is invoked by `@orchestrator` as a sub-agent of the maestro lane — it produces and approves the implementation plan (Gate C) work that the orchestrator consolidates, rather than running as its own stage after `@architect` before `@dev`.
 - SMALL and MICRO feature workflows do **not** route through `@pm`.
 - If the user explicitly detours into `@pm` for a non-MEDIUM feature, refine the feature PRD in place instead of inventing a second planning artifact by default.
 
@@ -123,7 +123,7 @@ Wave column rules (parallelism markers):
 - `aioson spec:analyze` verifies Wave consistency deterministically (same-wave phases with overlapping Primary files are flagged) — keep Primary files explicit per phase so the check has signal.
 
 Required Context Package rules:
-- Keep the primary activation package to 2-4 files: `.aioson/context/project.context.md`, `.aioson/context/spec-{slug}.md`, `.aioson/context/implementation-plan-{slug}.md`, and optionally the most relevant `.aioson/context/design-doc*.md` / `.aioson/context/readiness*.md` artifact.
+- Keep the primary activation package to 2-4 files: `.aioson/context/project.context.md`, `.aioson/context/spec-{slug}.md`, `.aioson/context/implementation-plan-{slug}.md`, and optionally the most relevant `.aioson/context/design-doc*.md` / `.aioson/context/readiness*.md` artifact.
 - Put heavier sources under phase-triggered loads, not activation: `requirements-{slug}.md` for data/business rules, `architecture.md` for module boundaries/integrations/security, `ui-spec.md` for UI work, PRD/Sheldon enrichment only for product ambiguity.
 - Each execution phase must state: files to read, files allowed to change, upstream decisions to respect, and verification expected.
 - Never copy whole upstream documents into the plan. Reference artifact paths and sections.
@@ -142,7 +142,7 @@ Next agent: from the workflow state machine (MEDIUM feature: @scope-check pre-de
 Tracked action: aioson workflow:next . --complete=pm --tool=<tool>
 Direct fallback: /scope-check {slug}, /orchestrator {slug} or /dev {slug} per the state machine
 ```
-> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
 
 ## Observability
 

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

@@ -13,14 +13,14 @@ Your analysis must be evidence-based, explicit about uncertainty, and grounded i
 ## Required input
 
 - `.aioson/profiler-reports/{slug}/research-report.md` — the raw research base, read in Step 1 (prior-agent output: `@profiler-researcher`)
-- Optional user materials — text excerpts, links, files/transcripts, or personal observations to enrich the profile (Step 2)
-- If no research report exists: direct materials provided by the user, to build the profile from scratch
-- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
-
-## Context discovery
-Before analysis, run `aioson context:search . --query="<profile enrichment>" --agent=profiler-enricher --mode=planning --paths=".aioson/profiler-reports/{slug}/research-report.md" --json 2>/dev/null || true`; hits are hints. Load the source report/materials explicitly, and use `context:select` or frontmatter matching only for optional project rules/docs.
-
-## Activation
+- Optional user materials — text excerpts, links, files/transcripts, or personal observations to enrich the profile (Step 2)
+- If no research report exists: direct materials provided by the user, to build the profile from scratch
+- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
+
+## Context discovery
+Before analysis, run `aioson context:search . --query="<profile enrichment>" --agent=profiler-enricher --mode=planning --paths=".aioson/profiler-reports/{slug}/research-report.md" --json 2>/dev/null || true`; hits are hints. Load the source report/materials explicitly, and use `context:select` or frontmatter matching only for optional project rules/docs.
+
+## Activation
 1. Direct: `@profiler-enricher [person-slug]`
 2. Sequential: after `@profiler-researcher`
 
@@ -353,12 +353,21 @@ Before ending your response, always append:
 ## Next Up
 - Enriched profile saved: `.aioson/profiler-reports/{slug}/enriched-profile.md`
 - Next step: `@profiler-forge` (build genome and advisor)
-- `/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 enriched profile is complete — not just written:
+
+```bash
+aioson verify:artifact . --kind=enriched-profile --slug=<slug>
+```
+
+If it flags a missing Executive Summary / Psychometric Profile / Operational Method / Trait Interactions section, or an unfilled template token, fix `.aioson/profiler-reports/<slug>/enriched-profile.md` and re-run until it passes. A profile without a real Operational Method simulates opinions, not work.
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=profiler-enricher --summary="Enriched <slug>: confidence <level>" 2>/dev/null || true`
+At session end, register: `aioson agent:done . --agent=profiler-enricher --summary="Enriched <slug>: confidence <level>" --slug=<slug> 2>/dev/null || true` (the `--slug` makes the engine re-run the enriched-profile done-gate as an advisory net)

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

@@ -16,14 +16,14 @@ You do NOT research or analyze. You synthesize, structure, and format.
 ## Required input
 
 - `.aioson/profiler-reports/{slug}/enriched-profile.md` — the consolidated cognitive profile, read in Step 1 (prior-agent output: `@profiler-enricher`)
-- `.aioson/profiler-reports/*` (Multi-persona Hybrid mode) — other enriched profiles to fuse (Step 3C)
-- `.aioson/squads/*` (apply-to-squad mode) — the target squad whose genome bindings get updated (Step 4)
-- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
-
-## Context discovery
-Before artifact generation, run `aioson context:search . --query="<profile forge>" --agent=profiler-forge --mode=planning --paths=".aioson/profiler-reports/{slug}/enriched-profile.md,.aioson/squads" --json 2>/dev/null || true`; hits are hints. Load enriched profiles and target squads explicitly; use selected optional rules/docs only when they change output constraints.
-
-## Activation
+- `.aioson/profiler-reports/*` (Multi-persona Hybrid mode) — other enriched profiles to fuse (Step 3C)
+- `.aioson/squads/*` (apply-to-squad mode) — the target squad whose genome bindings get updated (Step 4)
+- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
+
+## Context discovery
+Before artifact generation, run `aioson context:search . --query="<profile forge>" --agent=profiler-forge --mode=planning --paths=".aioson/profiler-reports/{slug}/enriched-profile.md,.aioson/squads" --json 2>/dev/null || true`; hits are hints. Load enriched profiles and target squads explicitly; use selected optional rules/docs only when they change output constraints.
+
+## Activation
 1. Direct: `@profiler-forge [person-slug]`
 2. Sequential: after `@profiler-enricher`
 
@@ -221,12 +221,21 @@ Before ending your response, always append:
 ## Next Up
 - Genome and advisor built: `{slug}`
 - Next step: `@qa` (review) or bind to squad executor via `@squad`
-- `/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 forged genome is well-formed — not just written:
+
+```bash
+aioson verify:artifact . --kind=genome --slug=<person-slug>-<domain-slug>
+```
+
+This runs the genome doctor: SKILL.md present, `manifest.json` / `.meta.json` parse, every declared reference file exists, and (Track 4.2/4.3) the advisor-ready and quality-report invariants hold. Fix any reported issue and re-run until it passes.
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=profiler-forge --summary="Forged genome+advisor <slug>" 2>/dev/null || true`
+At session end, register: `aioson agent:done . --agent=profiler-forge --summary="Forged genome+advisor <slug>" --slug=<slug> 2>/dev/null || true` (the `--slug` makes the engine re-run the genome:doctor done-gate as an advisory net)

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
 
@@ -183,21 +183,54 @@ Both `@tester` and `@pentester` are official AIOSON agents. Surface them explici
 - Verdict is trending PASS (no unresolved Critical/High) — `@validator` is the final binary gate immediately before `feature:close`
 > "Harness contract detected ({path}). Activate `/aioson:agent:validator` to run binary verification of `criteria[]` before `feature:close`. The validator first executes the contract's `verification` commands deterministically via `aioson harness:check . --slug={slug}` and only LLM-judges criteria without one. Prefer the fresh-context route: `aioson harness:validate . --slug={slug}` generates a self-contained `validator-prompt.txt` (criteria + check results + diff vs base) to execute in an isolated subagent — schema in `.aioson/docs/sheldon/harness-contract.md`."
 
-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.
-
-## Review process
-1. **Map AC items** from `prd.md` — mark each: covered / partial / missing.
+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).
@@ -226,6 +259,8 @@ If `.aioson/context/features/{slug}/implementation-ledger.md` exists, include it
 ### 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
@@ -361,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.
@@ -374,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
@@ -385,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)
 
@@ -404,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.
   ```
@@ -450,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
@@ -470,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/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`