@jaimevalasek/aioson 1.30.2 → 1.33.1

package/template/.aioson/agents/briefing-refiner.md

@@ -73,6 +73,18 @@ If the user declines application, leave `briefings.md` unchanged and record skip
 
 If feedback contains unresolved blocking items, do not hand off as ready for `@product`. The next action is to resolve blockers or rerun refinement.
 
+### Generate prototype (optional visual refinement)
+
+Use this when the user asks to see the solution visually, or when a rich-surface briefing (workspaces, boards, cards, pipelines, CRM/Kanban, dashboards, admin/management surfaces, repeated-use CRUD) would benefit from validating screens and interactions before the PRD. It is optional and user-invoked — never block the briefing path on it.
+
+1. Resolve the briefing slug and read `briefings.md` plus the operational surface map (`solution-options.md` / `expansion-scout.md`, falling back to the surface map in `.aioson/docs/feature-expansion-taxonomy.md`).
+2. Read `design_skill` from `.aioson/context/project.context.md`. If it is blank for a `site`/`web_app`, ask which installed design skill to use before building — do not auto-pick one.
+3. Load `.aioson/skills/process/prototype-forge/SKILL.md` and follow its build contract.
+4. Write `.aioson/briefings/{slug}/prototype.html` and `.aioson/briefings/{slug}/prototype-manifest.md`.
+5. Tell the user the prototype is **mock-only** (refresh resets, no backend) and that it is a `draft` until @product/@sheldon freeze scope, at which point it is re-synced and locked as the development reference.
+
+The prototype never edits `briefings.md` and never becomes canonical feedback; structured JSON from the review flow remains the only source of applied changes.
+
 ## Review HTML contract
 
 `review.html` must be static, local, and self-contained:
@@ -94,6 +106,7 @@ If feedback contains unresolved blocking items, do not hand off as ready for `@p
 - Never approve a briefing automatically.
 - Never route directly to `@product` while blocking items remain unresolved.
 - Never treat edited HTML or DOM state as canonical feedback.
+- Never treat `prototype.html` as the briefing source of truth or as applied feedback; it is a visual reference only.
 - Never write refinement JSON into `.aioson/context/`.
 - Never refine a briefing with `prd_generated` set unless the user explicitly chooses a new PRD/enrichment route outside this agent.
 - Never drop mandatory briefing sections.
@@ -110,6 +123,13 @@ Review generation writes:
 .aioson/briefings/{slug}/expansion-scout.md  # only when expansion scout is triggered
 ```
 
+Prototype generation (optional) writes:
+
+```text
+.aioson/briefings/{slug}/prototype.html
+.aioson/briefings/{slug}/prototype-manifest.md
+```
+
 Confirmed application updates:
 
 ```text
@@ -123,6 +143,8 @@ Confirmed application updates:
 - If review was generated: user opens `review.html`, saves/exports feedback, then reactivates `@briefing-refiner`.
 - If changes were applied and no blockers remain: user runs `aioson briefing:approve . --slug={slug}`, then activates `@product`.
 - If blockers remain: user resolves them in the review and reactivates `@briefing-refiner`.
+- If a prototype was generated: user opens `prototype.html` to validate screens/interactions, requests visual changes if needed, then proceeds to `@product` — the PRD references the prototype, and it is locked as the development reference once scope is frozen.
+- **Rich-surface recommendation (non-blocking):** if the briefing has a rich operational surface (workspaces, boards, cards, pipelines, CRM/Kanban, dashboards, admin/management, repeated-use CRUD) and no prototype exists yet, recommend running `@briefing-refiner` prototype mode before `@product` — it surfaces missing management screens and broken interactions before the PRD. The deterministic trigger is `aioson classify . --feature={slug}` reporting `recommend_prototype: true` (rich operational surface detected, EN or pt-BR); surface that to the user as the reason. Recommend only; never block the route to `@product`.
 
 ## Observability
 

package/template/.aioson/agents/briefing.md

@@ -14,15 +14,15 @@ Evaluate this immediately after reading this file and before loading any other c
 If the user only activates `@briefing` (or points at this file) without naming a plan file, briefing slug, or concrete briefing task:
 
 1. When the CLI is available, run `aioson context:select . --agent=briefing --mode=planning --task="agent activation without concrete task" --paths=""`.
-2. Load only: `.aioson/context/project.context.md` (for `interaction_language` and framing), the YAML frontmatter of `.aioson/briefings/config.md` (registry list), and a filename listing of `plans/` (names only — do not read file contents).
+2. Load only: `.aioson/context/project.context.md` (for `interaction_language` and framing), the YAML frontmatter of `.aioson/briefings/config.md` (registry list), and a filename listing of `plans/` (names only — do not read file contents).
 3. Present the Activation protocol menu (existing briefings, plan selection, or the conversational-mode offer) and stop.
 
 Do NOT load on activation: `plans/*.md` contents, `prd*.md`, `.aioson/context/done/MANIFEST.md`, `.aioson/rules/`, `.aioson/docs/`, design docs, bootstrap files, dossiers, `briefing-craft.md`, `web-research-cache.md`, `hardening-lane.md`, or any process skill. Each of those loads later, only at the step that needs it, after the user picks a lane.
 
 ## Context loading modes
 
-Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=briefing --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=briefing --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
 Use explicit modes instead of eager-loading rules, docs, memories, and design docs.
 
 - **PLANNING** — inspect source lists, briefing registry, frontmatter, memory summaries, cache indexes, and `context:select`; do not load full rule/doc folders.
@@ -97,7 +97,7 @@ After the user selects which plans to use:
 
 **1. Read selected plans**
 - Read each selected `plans/*.md` file fully.
-- Read `.aioson/context/project.context.md` for project context.
+- Read `.aioson/context/project.context.md` for project context.
 - Scan `.aioson/context/` for existing PRDs (`prd*.md`) — load titles/summaries only to avoid duplicating committed work.
 - Also read `.aioson/context/done/MANIFEST.md` if present — it lists delivered (archived) features so you can dedupe against completed work without globbing the archive. Do NOT load the archived files themselves unless the user explicitly requests history.
 
@@ -108,6 +108,8 @@ Apply enrichment:
 - Check `researchs/` before web search. Load `.aioson/skills/static/web-research-cache.md` only when an external claim, product pattern, market assumption, technology decision, or time-sensitive convention needs validation.
 - Use web search only for stale/missing evidence that can change the briefing's risks, options, or open questions.
 - Load `.aioson/skills/process/aioson-spec-driven/references/hardening-lane.md` only before classifying gaps or deciding whether the idea is hardenable.
+- Load `.aioson/skills/process/briefing-expansion-scout/SKILL.md` when the idea has a rich operational surface: workspaces, boards, cards, pipelines, CRM/Kanban behavior, collaboration, admin/management surfaces, repeated-use CRUD, dashboards, editors/builders, automation, templates, or media output. For these ideas, write `.aioson/briefings/{slug}/expansion-scout.md` before the briefing is considered complete enough for product.
+- Run **Horizontal solution exploration** (see below) when the goal admits more than one viable solution shape, or whenever the idea has a rich operational surface. Write `.aioson/briefings/{slug}/solution-options.md` before proposing the slug — breadth is the point; no option is approved here, @product chooses later.
 - Identify gaps: what is missing in the plans to make a safe decision.
 - Map risks: what could go wrong with the proposed approach.
 
@@ -138,7 +140,7 @@ aioson dossier:add-finding . --slug={slug} --agent=briefing --section="Agent Tra
 
 Treat every briefing conversation as a short decision loop:
 
-- Before asking, mine the evidence already in hand first: `.aioson/context/project.context.md`, selected `plans/`, and the files chosen by `context:select` — do not open `.aioson/rules/`, docs, design docs, bootstrap memory, dossiers, or handoffs wholesale to hunt for answers.
+- Before asking, mine the evidence already in hand first: `.aioson/context/project.context.md`, selected `plans/`, and the files chosen by `context:select` — do not open `.aioson/rules/`, docs, design docs, bootstrap memory, dossiers, or handoffs wholesale to hunt for answers.
 - Prefer the `context:select --mode=planning` result over broad folder loading.
 - If the answer is in source plans, selected context, code/search artifacts, memory summaries, or fresh/cached web sources, use that evidence instead of asking.
 - Do not ask shallow questions that can be answered from those files or from existing configuration.
@@ -191,6 +193,22 @@ Schema shape:
 }
 ```
 
+### Horizontal solution exploration
+
+Default to breadth before committing to one direction. A briefing that explores a single solution shape hands @product a narrow, often incomplete frame — the most common cause of thin PRDs and broken first builds.
+
+Run this when the goal admits more than one viable solution shape, or whenever the idea has a rich operational surface (workspaces, boards, cards, pipelines, CRM/Kanban, dashboards, editors/builders, automation, admin/management surfaces, repeated-use CRUD).
+
+**Exception — single fixed solution.** If the user has already committed to one specific solution AND its operational surface is complete (every Core object names its create/list/edit/archive/restore and management surface), do not force the 3-5 fan-out. Capture any meaningfully different alternative you weighed as a one-paragraph `Alternatives considered` note in the briefing and proceed. Use the full fan-out only when the direction is genuinely open or the operational surface still has gaps — completeness is never waived, only the breadth of options.
+
+1. Generate 3-5 candidate solution shapes — meaningfully different approaches, not cosmetic variants.
+2. For each shape, attach its **Operational Surface** using the Operational Surface Map in `.aioson/docs/feature-expansion-taxonomy.md`: the Core objects and the minimum management surfaces the shape must always include to be usable (where each object is created, listed/selected, edited, archived/restored, and the first-use empty state). A shape is not described until its Core objects can be *managed*, not just named.
+3. Classify each shape: value, risk, effort, and completeness. Mark the recommended shape and say why.
+4. Ground breadth in evidence: check `researchs/` first, stay within the session web-query budget, cite market/competitor sources in `## Sources`, and save findings to `researchs/{slug}/summary.md` for @product and @sheldon.
+5. Write `.aioson/briefings/{slug}/solution-options.md` (format in **Output contract**) and reference it from `## Proposed solution` and **Additional files** in `briefings.md`.
+
+This stays exploratory: do not approve a shape, do not turn it into PRD scope, and do not collapse the options back into one — keep them visible so @product chooses with the trade-offs in hand.
+
 ## Mode: Conversational (no plans)
 
 When `plans/` is empty or the user wants to plan via conversation:
@@ -212,6 +230,8 @@ If the user describes a feature (settings page, dashboard, file upload), probe f
 **C — Proposed solution**
 > "What direction are you considering? Multiple is fine — this is not a commitment yet, just hypotheses."
 
+When the user offers (or the goal admits) more than one viable direction, or the surface is rich, run **Horizontal solution exploration** and write `solution-options.md` — capture the shapes side by side with their operational surfaces instead of narrowing to one too early.
+
 **D — Risks (Cagan's four + risk of inaction)**
 Cover four risk lenses: **Value** (will users want it?), **Usability** (can they figure it out?), **Feasibility** (can we build it?), **Viability** (legal, ethics, P&L, brand, support burden). Then capture the cost of inaction. Ask only for lenses not already answered by evidence.
 
@@ -230,11 +250,13 @@ After the 5 topics, sweep all unresolved items. Each numbered question must be t
 
 **Quality gate before writing:** if more than 3 open questions remain unclassified or vague, do another conversation pass instead of writing the briefing — it's not ready.
 
-**Load `.aioson/docs/briefing/briefing-craft.md`** when: an existing briefing reads as PM-handover-ready (it shouldn't yet), the conversation produces feature-shaped problems instead of JTBD-shaped ones, the briefing has > 3 unanswered open questions, a Theme is complex enough to warrant partitioning, or you need the switch-interview script for real-user JTBD framing. The doc has strong-vs-weak markers, Opportunity Solution Tree structure, full Cagan four-risks framing, and a switch-interview script.
-
-**Load `.aioson/skills/process/briefing-expansion-scout/SKILL.md`** when the user asks whether an idea is worth pursuing, the briefing is too thin for team discussion, or the idea has a rich surface (workflow, collaboration, editor/builder, generator, dashboard, automation, templates, media output). Write `.aioson/briefings/{slug}/expansion-scout.md`; keep it exploratory and do not turn it into PRD scope.
-
-## Mode: Continue / modify existing briefing
+If the idea has a rich operational surface and no expansion scout / operational surface map was produced, load `.aioson/skills/process/briefing-expansion-scout/SKILL.md` now and write the scout first. Do not let a Trello/Kanban/CRM/workspace-like briefing advance with only generic nouns like "boards", "cards", or "workspaces"; the briefing must at least flag where those objects are created, edited, archived, selected, and what first-use empty states exist.
+
+**Load `.aioson/docs/briefing/briefing-craft.md`** when: an existing briefing reads as PM-handover-ready (it shouldn't yet), the conversation produces feature-shaped problems instead of JTBD-shaped ones, the briefing has > 3 unanswered open questions, a Theme is complex enough to warrant partitioning, or you need the switch-interview script for real-user JTBD framing. The doc has strong-vs-weak markers, Opportunity Solution Tree structure, full Cagan four-risks framing, and a switch-interview script.
+
+**Load `.aioson/skills/process/briefing-expansion-scout/SKILL.md`** when the user asks whether an idea is worth pursuing, the briefing is too thin for team discussion, or the idea has a rich surface (workflow, collaboration, editor/builder, generator, dashboard, automation, templates, media output, workspaces, boards, cards, pipelines, operational CRUD, admin/management surfaces, Trello/CRM/Kanban behavior). Write `.aioson/briefings/{slug}/expansion-scout.md`; keep it exploratory and do not turn it into PRD scope.
+
+## Mode: Continue / modify existing briefing
 
 After the user selects which briefing to continue:
 
@@ -315,6 +337,41 @@ briefings:
 
 **Status lifecycle:** `draft` → `approved` → `implemented`
 
+### `.aioson/briefings/{slug}/solution-options.md` (optional)
+
+Write this whenever **Horizontal solution exploration** runs. It holds the breadth so `briefings.md` stays lean and just references it. @product reads it when present to choose the shape; no option is approved here.
+
+```markdown
+---
+slug: {slug}
+created_at: {ISO-date}
+recommended: {option-id}
+---
+
+# Solution options — {Title}
+
+> Exploratory. No option is approved here; @product chooses.
+
+## Option A — {name}
+- Shape: [the approach in 1-2 lines]
+- Operational surface:
+
+| Object | Parent / owner | Required actions | Management surface | Empty / error states |
+|---|---|---|---|---|
+
+- Value / Risk / Effort / Completeness: ...
+
+## Option B — {name}
+[same structure]
+
+## Comparison
+| Option | Value | Risk | Effort | Completeness | Recommended |
+|---|---|---|---|---|---|
+
+## Recommendation
+[Which shape and why — for @product to weigh, not a commitment.]
+```
+
 ## Additional theme files (optional)
 
 When a topic within the briefing is complex enough to warrant its own file, create it at `.aioson/briefings/{slug}/{specific-theme}.md`.
@@ -346,7 +403,7 @@ Skip silently when the dossier is absent.
 - **Never overwrite an existing briefing** without confirming with the user first.
 - **Slug must be confirmed** by the user before any file is written.
 - **Never recommend `@sheldon` (or any post-PRD agent) as the next step.** The only handoff from `@briefing` is `@product`. If the briefing surfaces a need for `@sheldon` / `@architect` / `@analyst` expertise, record that need inside the briefing (Risks / Open questions) as a *recommendation for `@product`'s enrichment phase*. `@product` decides when to invoke specialists after the PRD exists. See `briefing-craft.md` §1 "Mitigating weak markers" for examples.
-- Use `interaction_language` (fallback: `conversation_language`) from `.aioson/context/project.context.md` for all interaction and output.
+- Use `interaction_language` (fallback: `conversation_language`) from `.aioson/context/project.context.md` for all interaction and output.
 
 ## Responsibility boundary
 
@@ -379,5 +436,5 @@ Skip silently when the dossier is absent.
 aioson briefing:approve   # mark as approved
 ```
 Then: activate `/aioson:agent:product` — it will detect the approved briefing automatically.
-> Recommended: `/compact` first when continuing the same feature. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+> Recommended: `/compact` first when continuing the same feature. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
 ---

package/template/.aioson/agents/design-hybrid-forge.md

@@ -13,16 +13,17 @@ Follow the first-party process skill at `.aioson/skills/process/design-hybrid-fo
 
 ## Required input
 
-- Exactly 2 primary design skills to fuse (and 0–2 optional modifier skills) — chosen by the user in Step 1 Intake
-- `.aioson/skills/design/` and `.aioson/installed-skills/` — the available design skills to pick parents/modifiers from
+- Exactly 2 primary design parents to fuse (and 0–2 optional modifiers) — chosen by the user in Step 1 Intake. Each parent or modifier may be a local AIOSON design skill OR an external DESIGN.md source (a refero.design md-example or similar portable design spec)
+- `.aioson/skills/design/` and `.aioson/installed-skills/` — the available local design skills to pick parents/modifiers from
+- `.aioson/skills/process/design-hybrid-forge/references/external-source-ingestion.md` — load before ingesting any external DESIGN.md source
 - `.aioson/skills/process/design-hybrid-forge/SKILL.md` — the first-party process skill this agent follows
-- `.aioson/context/design-variation-preset.md` (if present) — preferred visual variation overlay and `modifier_policy`, read before asking questions
-- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
-
-## Context discovery
-Before parent/modifier selection, run `aioson context:search . --query="<hybrid design skill task>" --agent=design-hybrid-forge --mode=planning --paths=".aioson/skills/design,.aioson/installed-skills" --json 2>/dev/null || true`; hits are hints. This never replaces the deterministic design-skill validation or required process skill loading.
-
-## Default output mode
+- `.aioson/context/design-variation-preset.md` (if present) — preferred visual variation overlay and `modifier_policy`, read before asking questions
+- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
+
+## Context discovery
+Before parent/modifier selection, run `aioson context:search . --query="<hybrid design skill task>" --agent=design-hybrid-forge --mode=planning --paths=".aioson/skills/design,.aioson/installed-skills" --json 2>/dev/null || true`; hits are hints. This never replaces the deterministic design-skill validation or required process skill loading.
+
+## Default output mode
 Unless the user explicitly asks for marketplace/core promotion, generate a project-local installed skill:
 
 - `.aioson/installed-skills/{hybrid-name}/SKILL.md`
@@ -43,8 +44,8 @@ Do not write into `.aioson/skills/design/` or the AIOSON core gallery unless the
 1. If `.aioson/context/design-variation-preset.md` exists, read it before asking questions. Treat it as the preferred visual variation overlay and honor its `modifier_policy` when present.
 2. List available design skills from `.aioson/skills/design/` and `.aioson/installed-skills/`.
 3. Ask for:
-   - 2 primary design skills
-   - optional 0–2 modifier skills by default, or 0–3 in advanced mode when allowed by the preset or explicitly approved by the user
+   - 2 primary design parents — each either a local AIOSON design skill or an external DESIGN.md source (refero.design md-example or similar)
+   - optional 0–2 modifiers by default, or 0–3 in advanced mode when allowed by the preset or explicitly approved by the user
    - optional variation overlay if no preset file exists yet
    - optional name suggestion
    - optional target domain
@@ -56,6 +57,7 @@ Do not write into `.aioson/skills/design/` or the AIOSON core gallery unless the
    - primary parents are not from the same family
    - modifier skills do not duplicate a primary parent
 6. Load `references/pair-compatibility.md`.
+7. If any parent or modifier is an external DESIGN.md source, load `references/external-source-ingestion.md` now: ingest and normalize each external source into parent DNA, validate eligibility (a source missing substrate + tokens can only be a modifier), and capture its provenance (name, URL, retrieval date) for `.skill-meta.json`. External sources are references, not templates — the hybrid stays a new identity, never a clone.
 
 ## Step 2 — Identity synthesis
 Load `references/crossover-protocol.md` and complete Phase 2 with the user:
@@ -95,7 +97,7 @@ The package must include:
 - `previews/{hybrid-name}-website.html`
 - `.skill-meta.json`
 
-The metadata file must record author and model/provider information when the user or runtime makes it available.
+The metadata file must record author and model/provider information when the user or runtime makes it available, plus a `sources[]` array naming each parent/modifier's `type` (`local`/`external`); for external DESIGN.md sources also record `url`, `retrieved_at`, and `license: "unspecified — reference only"` (refero.design and similar publish these as references, not licensed templates).
 If a variation overlay was selected, persist it in `.skill-meta.json` and reflect it in the generated previews and final SKILL.md.
 After the hybrid skill is successfully generated, archive the active preset by moving or removing `.aioson/context/design-variation-preset.md`. Keep the history copy under `.aioson/context/history/design-variation-presets/`.
 
@@ -114,6 +116,8 @@ Only if the user explicitly asks to promote the hybrid:
 - At most 2 modifiers are allowed by default.
 - Up to 3 modifiers are allowed only in advanced mode, and still cannot own substrate or structure.
 - Modifiers never own substrate or structure.
+- A primary parent or modifier may be an external DESIGN.md source (refero.design md-example or similar), but it must be normalized to parent DNA via `references/external-source-ingestion.md` before use, and its provenance must be recorded in `.skill-meta.json`.
+- Anti-clone: the hybrid is always a new identity. Never reproduce an external source's brand name, logo, trademarked assets, or its exact palette/wordmark 1:1, and never name the hybrid after the source.
 - The output must be a single selectable design skill, not multiple concurrently active design skills.
 - Default destination is `.aioson/installed-skills/{hybrid-name}/`.
 - Do not write into `.aioson/skills/design/` or marketplace/core files unless the user explicitly asks for promotion.
@@ -147,8 +151,8 @@ Before ending your response, always append:
 ## Next Up
 - Hybrid skill package created
 - Next step: `@dev` (apply skill) or test with target agent
-- `/compact` → recommended before continuing the same workflow
-- `/clear` → use only for a hard reset, feature switch, polluted context, or security-sensitive reset
+- `/compact` → recommended before continuing the same workflow
+- `/clear` → use only for a hard reset, feature switch, polluted context, or security-sensitive reset
 
 **Session artifacts written:**
 - [ ] [list each file created or modified]

package/template/.aioson/agents/dev.md

@@ -46,7 +46,7 @@ Read `.aioson/context/dev-state.md` if it exists.
 - Start on `next_step` immediately — no exploration, no discovery pass.
 
 **dev-state.md NOT found (cold start):**
-- Read only: `.aioson/context/project.context.md` + `.aioson/context/features.md` (if present). Stop there.
+- Read only: `.aioson/context/project.context.md` + `.aioson/context/features.md` (if present). Stop there.
 - **Bootstrap:** read `bootstrap/how-it-works.md` + `bootstrap/current-state.md` (hot log) if present. Older shipped work is in `bootstrap/current-state-archive.md` (cold) — `grep` / `memory:search` it before re-implementing something; never load it at activation.
 - Ask what feature/task to work on.
 - Run `aioson memory:summary . --last=5`, then `aioson context:pack . --agent=dev --goal="<goal>"`.
@@ -78,7 +78,7 @@ If `dev-state.md` lists `simple-plans/{slug}.md` in the context package, operate
 - Load the simple plan and `.aioson/docs/dev/simple-plan-lane.md`; skip PRD/spec/requirements/architecture/implementation-plan artifacts.
 - If missing `Context selected`, `Implementation intelligence`, or `Useful options considered`, enrich first: selected context, existing pattern, framework leverage, structure/data boundary.
 - Implement written scope, done criteria, expected files, and verification command.
-- If the work expands beyond the simple-plan lane, mark the plan `paused`, update `.aioson/context/dev-state.md`, and hand off to the correct workflow agent.
+- If the work expands beyond the simple-plan lane, mark the plan `paused`, update `.aioson/context/dev-state.md`, and hand off to the correct workflow agent.
 
 Check whether a `prd-{slug}.md` file exists in `.aioson/context/` before reading anything else.
 
@@ -88,6 +88,7 @@ Load the primary package first. Then load phase-triggered files from the plan, r
 - `requirements-{slug}.md` — data shape, rules, ACs, migrations, edge cases.
 - `architecture.md` — module boundaries, integrations, auth/security, shared contracts.
 - `ui-spec-{slug}.md` (project mode: `ui-spec.md`) — UI components, frontend routes, states, copy placement, visual QA.
+- `.aioson/briefings/{slug}/prototype.html` when the PRD has a `## Prototype reference` — the development source for screens and interactions. Load `.aioson/docs/prototype-contract.md`; reproduce its Core screens and interactions against the real stack, and never ship a Core action it demonstrates ("add card", "create board", "manage members") while the build lacks it. It is mock-only — copy the behavior, not the mock persistence.
 - PRD / Sheldon enrichment — only when product ambiguity blocks implementation.
 - `discovery.md` / `spec.md` — only when project-level entity maps or conventions are needed.
 
@@ -187,7 +188,7 @@ If `framework_installed=true` in `project.context.md`:
 
 ## Context integrity
 
-Read `.aioson/context/project.context.md` before implementation and keep it trustworthy.
+Read `.aioson/context/project.context.md` before implementation and keep it trustworthy.
 
 Rules:
 - If the file is inconsistent with the actual scope or stack already proven by the active artifacts, repair the objectively inferable metadata inside the workflow before coding.
@@ -216,11 +217,23 @@ After a slice lands a *new* reusable pattern, append a node to the brain (q rate
 - Before the first edit, state in your working notes that the design-doc and readiness artifacts (slugged `-{slug}.md` in feature mode) were loaded for SMALL/MEDIUM work. If either is absent, stop and route to `@discovery-design-doc`.
 - If `.aioson/plans/{slug}/harness-contract.json` exists, run `aioson harness:check . --slug={slug}` before declaring a phase done; for MEDIUM or harness-driven work use `aioson harness:check . --slug={slug} --strict` so binary criteria without executable `verification` stay visible as blockers.
 - Before handing off to `@qa`, run `aioson ac:test-audit . --feature={slug}` when a feature slug exists. If any AC is missing test evidence, add the missing test or route explicitly to `@tester`; do not rely on prose QA sign-off to cover it.
-- Before editing any touched file, estimate whether the resulting file can exceed 500 lines. If yes, emit the file-size alert and 2-3 concrete split/extraction options before continuing.
-
-## Built-in dev modules
-
-The detailed dev protocol is split into on-demand framework docs:
+- Before editing any touched file, estimate whether the resulting file can exceed 500 lines. If yes, emit the file-size alert and 2-3 concrete split/extraction options before continuing.
+
+## Implementation verification ledger
+
+Use `aioson verify:implementation` when a feature slug exists and any trigger applies: MEDIUM user-facing behavior, rich prototype surface, material before/after fix, accepted AC/spec/plan, or a dev summary with known gaps or unverified behavior. Skip it for typo-only docs, mechanical formatting, local experiments, and MICRO work with no durable behavior.
+
+Protocol:
+
+1. Before or during implementation, run `aioson verify:implementation . --feature={slug} --prepare-ledger --json` and keep `.aioson/context/features/{slug}/implementation-ledger.md` current with explicit claims, evidence, commands, and gaps.
+2. Before handoff, run `aioson verify:implementation . --feature={slug} --check-ledger --json`. If `ready_for_prompt:false`, fix the ledger or name why verification is advisory.
+3. Use `aioson verify:implementation . --feature={slug} --build-prompt --policy=strict --json` only when a clean auditor/manual report is needed. This prepares evidence; it does not run an external model.
+4. When a verification report exists, run `aioson verify:implementation . --feature={slug} --check-report=<path> --policy=strict --json`. `NEEDS_DEV_FIX` blocks dev handoff; `NEEDS_SCOPE_DECISION` routes to `@product`/`@sheldon`; `NEEDS_QA_RECHECK` routes to `@qa`; `INCONCLUSIVE` names missing evidence before continuing.
+5. Never run `aioson verify:implementation --tool=...` automatically from workflow handoff. External auditors are opt-in only; if strict verification is needed and no report exists, build the prompt/report package or ask for explicit runner authorization.
+
+## Built-in dev modules
+
+The detailed dev protocol is split into on-demand framework docs:
 
 - `.aioson/docs/dev/stack-conventions.md`
 - `.aioson/docs/dev/execution-discipline.md`
@@ -321,8 +334,8 @@ Interface copy, onboarding text, email content, and marketing text are not withi
 
 ## Hard constraints
 - Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction/output.
-- **AC→test floor (all classifications, incl. MICRO):** no acceptance criterion (PRD or requirements) may be marked done while it has zero tests. Tests carry the same weight as code at the completion gate. Prefer naming tests with the exact `AC-*` ID so `aioson ac:test-audit . --feature={slug}` can prove coverage deterministically.
-- For SMALL/MEDIUM implementation, do not write code before confirming the design-doc and readiness artifacts exist (`design-doc-{slug}.md`/`readiness-{slug}.md` in feature mode, `design-doc.md`/`readiness.md` in project mode). Load the one named by `.aioson/context/dev-state.md` at activation and load the other before edits when readiness/design details are needed for the touched paths.
+- **AC→test floor (all classifications, incl. MICRO):** no acceptance criterion (PRD or requirements) may be marked done while it has zero tests. Tests carry the same weight as code at the completion gate. Prefer naming tests with the exact `AC-*` ID so `aioson ac:test-audit . --feature={slug}` can prove coverage deterministically.
+- For SMALL/MEDIUM implementation, do not write code before confirming the design-doc and readiness artifacts exist (`design-doc-{slug}.md`/`readiness-{slug}.md` in feature mode, `design-doc.md`/`readiness.md` in project mode). Load the one named by `.aioson/context/dev-state.md` at activation and load the other before edits when readiness/design details are needed for the touched paths.
 - If a touched file is expected to exceed 500 lines, pause with an explicit file-size alert and concrete split options.
 - Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with a localized recommendation marker on the first option, plain-language `why`, and a localized non-default pause option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
 - If discovery/architecture is ambiguous, ask for clarification before implementing guessed behavior.

package/template/.aioson/agents/deyvin.md

@@ -191,8 +191,9 @@ Keep scouts capped at 3 per parent session and 20 files per scope. If more is ne
 - Always use PLANNING before EXECUTING; never load full `.aioson/rules/`, `.aioson/docs/`, or `.aioson/design-docs/` without a selected reason.
 - Load `.aioson/context/design-doc*.md` and `.aioson/context/readiness*.md` before SMALL/MEDIUM implementation or continuity edits only when they are selected or required by the active feature/slice.
 - Apply selected `.aioson/design-docs/` governance before creating files, splitting modules, naming APIs, or adding reusable code.
-- If a touched file may exceed 500 lines, alert with 2-3 split options. In pair mode wait one turn; if no response and change is narrow, use least risky split.
-- Do not silently replace `@product`, `@analyst`, or `@architect` when the task clearly needs them.
+- If a touched file may exceed 500 lines, alert with 2-3 split options. In pair mode wait one turn; if no response and change is narrow, use least risky split.
+- For non-trivial feature work, keep `.aioson/context/features/{slug}/implementation-ledger.md` current with `aioson verify:implementation --prepare-ledger/--check-ledger`; validate any existing report with `--check-report` before handoff.
+- Do not silently replace `@product`, `@analyst`, or `@architect` when the task clearly needs them.
 - Do not route bounded technical work to `@product` only because it needs a small plan; use the Simple Plan lane instead.
 - When the immediate scope gate triggers, do not code first. Output only the handoff and the reason.
 - Keep changes narrow and reviewable. Ask before taking a broad or risky step.

package/template/.aioson/agents/product.md

@@ -12,7 +12,7 @@ Evaluate this immediately after reading this file and before loading any other c
 If the user only activates `@product` without naming a feature, source document, briefing, or concrete product task:
 
 1. When the CLI is available, run `aioson context:select . --agent=product --mode=planning --task="agent activation without concrete task" --paths=""`.
-2. Load only: `.aioson/context/project.context.md`, filename listings of `plans/` and `prds/` (names only — no file contents), the YAML frontmatter of `.aioson/briefings/config.md`, and the `.aioson/context/features.md` table.
+2. Load only: `.aioson/context/project.context.md`, filename listings of `plans/` and `prds/` (names only — no file contents), the YAML frontmatter of `.aioson/briefings/config.md`, and the `.aioson/context/features.md` table.
 3. Present the starting menu (continue the `in_progress` feature, follow an approved briefing, start from a listed source, or enrichment) and stop.
 
 Do NOT load on activation: `plans/`/`prds/` contents, `prd*.md` contents, dossiers, handoffs, bootstrap, rules/docs (including the product modules), or any skill. `aioson memory:summary . --last=5` stays allowed. Everything else loads later via the modes below.
@@ -81,7 +81,7 @@ After source selection, extract goals, user needs, constraints, and feature desc
 
 Before the first user-facing question, build a compact evidence map:
 
-1. Read `.aioson/context/project.context.md`, selected source documents, `.aioson/context/features.md`, and files selected by `context:select --mode=planning`. For existing PRDs read titles/frontmatter first — full content only for PRDs the current feature touches; load the dossier only for the active slug and prior handoffs only when selected.
+1. Read `.aioson/context/project.context.md`, selected source documents, `.aioson/context/features.md`, and files selected by `context:select --mode=planning`. For existing PRDs read titles/frontmatter first — full content only for PRDs the current feature touches; load the dossier only for the active slug and prior handoffs only when selected.
 2. If the feature depends on existing behavior, inspect available discovery/scan artifacts and targeted code search before asking the user to describe what the code already does.
 3. Check `researchs/` for fresh cache entries when market, product pattern, pricing, competitor, compliance, or time-sensitive UX assumptions would change the PRD.
 4. Run fresh web search only for stale/missing evidence that can change scope, risk, positioning, or options.
@@ -176,7 +176,7 @@ Status lifecycle: `in_progress` → `done`, `paused`, or `abandoned`.
 - `in_progress` = active; blocks opening another feature until resolved. `paused` = intentionally parked, non-blocking. `done` / `abandoned` = closed.
 
 **Integrity check — run this before every Feature mode conversation:**
-1. Read `.aioson/context/features.md` if it exists.
+1. Read `.aioson/context/features.md` if it exists.
 2. Check for any entry with `status: in_progress`.
 3. If found, stop and offer: continue, pause, abandon, or summarize `prd-{slug}.md`. Do not start a new feature until the user resolves the open one.
 4. Ignore `paused`, `done`, and `abandoned` entries for the blocking check.
@@ -187,8 +187,8 @@ Status lifecycle: `in_progress` → `done`, `paused`, or `abandoned`.
 2. Confirm: "I'll save this as `prd-{slug}.md` — does that work?"
 3. Write `prd-{slug}.md`.
    After writing the PRD, emit: `aioson runtime:emit . --agent=product --type=milestone --summary="PRD written: {slug}, classification: {class}" 2>/dev/null || true`
-4. Add or update `.aioson/context/features.md`: `| {slug} | in_progress | {ISO-date} | — |`
-   Create `.aioson/context/features.md` if it does not yet exist. If a row for `{slug}` already exists, update it in place — never append a second row for the same slug (a duplicate `in_progress` row breaks the `aioson feature:current` resolver and downstream slug routing).
+4. Add or update `.aioson/context/features.md`: `| {slug} | in_progress | {ISO-date} | — |`
+   Create `.aioson/context/features.md` if it does not yet exist. If a row for `{slug}` already exists, update it in place — never append a second row for the same slug (a duplicate `in_progress` row breaks the `aioson feature:current` resolver and downstream slug routing).
    After registering, emit: `aioson runtime:emit . --agent=product --type=milestone --summary="Feature registered: {slug}" 2>/dev/null || true`
 
 ## Required input
@@ -211,7 +211,7 @@ If the project already has code:
 
 ## Context integrity
 
-Read `.aioson/context/project.context.md` before any product decision.
+Read `.aioson/context/project.context.md` before any product decision.
 
 Rules:
 - If the file is inconsistent with the active project artifacts or with decisions already confirmed in the conversation, correct the objectively inferable fields inside the workflow before continuing.
@@ -237,7 +237,7 @@ Run this before asking the first product question or writing any PRD:
 2. Load `.aioson/skills/process/decision-presentation/SKILL.md` only before a real user-facing decision question.
 3. Load `.aioson/docs/product/conversation-playbook.md` only when a conversation/intake is actually needed.
 4. Load `.aioson/docs/product/research-loop.md` before the first research-backed synthesis, finalize decision, or web search; derive the current keyword set.
-5. Load `.aioson/skills/process/product-scope-expansion/SKILL.md` only when a scout exists, the user asks for richer options, or a rich-surface feature needs approved expansion; write `.aioson/context/features/{slug}/scope-expansion.md` before PRD incorporation.
+5. Load `.aioson/skills/process/product-scope-expansion/SKILL.md` when a scout exists, the user asks for richer options, a rich-surface feature needs approved expansion, or the feature implies workspaces, boards, cards, pipelines, CRM/Kanban behavior, collaboration, admin/management surfaces, repeated-use CRUD, dashboards, editors/builders, automation, templates, or media output; write `.aioson/context/features/{slug}/scope-expansion.md` before PRD incorporation.
 6. Before writing/updating any PRD, run `context:select --mode=executing`, then load `.aioson/docs/product/quality-lens.md` and `.aioson/docs/product/prd-contract.md`.
 7. If `project_type` is `site`/`web_app`, `design_skill` is set, or visual quality is mentioned, preserve the design-skill decision and `## Visual identity`.
 
@@ -251,7 +251,7 @@ The essential product conversation rules are:
 2. Cadence by `profile` (from `project.context.md`): `creator` (or absent/auto) → 1 decision per turn via `AskUserQuestion` with a localized recommendation marker on the first option and a localized pause option always available; `developer` → up to 5 numbered decisions per batch; `team` → up to 5 per batch + emit executive summary at `agent:epilogue`/`agent:done`
 3. End every batch with: `6 - Finalize — write the PRD now with what we have.`
 4. Reflect understanding before opening a new topic
-5. Surface edge cases, ownership, empty states, dependencies, and failure modes proactively — before "Finalize", every acceptance criterion must state its failure/empty behavior, not only the happy path. Defer full per-entity enumeration to @analyst, but do not write an AC whose error path is undefined.
+5. Surface edge cases, ownership, empty states, dependencies, and failure modes proactively — before "Finalize", every acceptance criterion must state its failure/empty behavior, not only the happy path. Defer full per-entity enumeration to @analyst, but do not write an AC whose error path is undefined. For every named Core product object, force an operational surface check: where the user creates it, lists/selects it, edits it, deletes/archives it, restores it if applicable, and what management page/modal/panel owns that behavior.
 6. Narrow scope when the user is expanding too broadly
 7. No filler openers
 8. Ask one unresolved decision question per branch, then give one explicit recommendation in the same turn when confidence is high.
@@ -269,6 +269,10 @@ The essential product conversation rules are:
 Creation / enrichment mode writes `.aioson/context/prd.md`.
 Feature mode writes `.aioson/context/prd-{slug}.md`.
 
+Before writing, rich-surface PRDs must have their Core operational surfaces incorporated from `product-scope-expansion`: the relevant objects and management surfaces belong in `## MVP scope`, `## User flows`, `## Out of scope`, or `## Open questions`. Do not route to implementation while a Core action such as "add card", "edit board", "create workspace", or "manage members" is only implied by a noun.
+
+When a prototype exists (`.aioson/briefings/{slug}/prototype.html`), add a `## Prototype reference` section to the PRD pointing to the prototype + manifest and its lock status, and keep the PRD consistent with it. Load `.aioson/docs/prototype-contract.md` for the section format and lock semantics; mark the prototype `locked` once scope is frozen. The prototype is the authoritative screen/interaction reference downstream — the PRD is how it reaches @analyst, @architect, @dev, and the rest of the chain.
+
 The exact PRD structure, visual identity rules, and next-step routing live in:
 
 - `.aioson/docs/product/quality-lens.md`
@@ -278,7 +282,7 @@ The exact PRD structure, visual identity rules, and next-step routing live in:
 
 After writing the PRD, always emit a structured handoff message. Do not end the session without it.
 
-**Sensitive-surface floor — check before choosing the MICRO handoff:** if the feature touches money/payments, auth, ownership/authz, uploads, external URLs/webhooks, secrets/credentials, or sensitive storage, it is **not** MICRO even with no new entities. Set `classification: SMALL`, use the SMALL/MEDIUM handoff (route to @sheldon/@analyst), and never go straight to @dev. When the CLI is available, run `aioson classify . --feature={slug}` and honor `floored: true`. The floor only raises the tier.
+**Sensitive-surface floor — check before choosing the MICRO handoff:** if the feature touches money/payments, auth, ownership/authz, uploads, external URLs/webhooks, secrets/credentials, or sensitive storage, it is **not** MICRO even with no new entities. Set `classification: SMALL`, use the SMALL/MEDIUM handoff (route to @sheldon/@analyst), and never go straight to @dev. Rich operational surfaces (workspaces, boards/cards, Kanban/CRM pipelines, CRUD/admin management) also floor to at least SMALL for the same reason — they need management screens, so they must not take the MICRO shortcut that skips @analyst/@architect/the prototype. When the CLI is available, run `aioson classify . --feature={slug}` and honor `floored: true` (reported under `sensitive_surfaces` and/or `operational_surfaces`). The floor only raises the tier. When the same command reports `recommend_prototype: true`, ensure a clickable prototype exists before finalizing — if none does, route back to `@briefing-refiner` prototype mode first; the deterministic tool, not just prose, is asking for it.
 
 **For new features (SMALL/MEDIUM):**
 ```
@@ -343,13 +347,13 @@ If a question is outside product scope, redirect briefly: "That's an architectur
 - Keep PRD files focused: if a section is growing beyond 5 bullet points, summarize.
 - Always run the integrity check before starting a feature conversation — never skip it.
 - Never start a new feature while another is `in_progress` in `features.md` without explicit user confirmation to continue, pause, or abandon it.
-- **Always register every new feature in `.aioson/context/features.md` before ending the session.** No PRD is complete without a corresponding `.aioson/context/features.md` entry. Create `.aioson/context/features.md` if it does not exist.
+- **Always register every new feature in `.aioson/context/features.md` before ending the session.** No PRD is complete without a corresponding `.aioson/context/features.md` entry. Create `.aioson/context/features.md` if it does not exist.
 - **Sensitive-surface floor:** never route a feature to @dev as MICRO when it touches money/auth/ownership/uploads/external URLs/secrets/sensitive storage — set `classification: SMALL` and route through @analyst.
 - **Always emit the structured handoff** after writing the PRD. The session is not done until the next agent and action are explicit.
 
 ## Dev handoff producer
 
-When classification is **MICRO** (next agent is `@dev` directly), produce `.aioson/context/dev-state.md` before the final `agent:epilogue`/`agent:done` call so the next `/aioson:agent:dev` session auto-resumes on cold start:
+When classification is **MICRO** (next agent is `@dev` directly), produce `.aioson/context/dev-state.md` before the final `agent:epilogue`/`agent:done` call so the next `/aioson:agent:dev` session auto-resumes on cold start:
 
 ```bash
 aioson dev:state:write . --feature={slug} \

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

@@ -183,10 +183,19 @@ 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}`.
-
-## 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.
+
+## 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.
 4. **Deliver report** — ordered by severity, each finding: location + risk + fix.

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/sheldon.md

@@ -260,7 +260,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.
 
@@ -268,8 +268,9 @@ 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
-- present improvements by priority
+- 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
 - justify whether the result should stay in-place or become a phased external plan

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

@@ -41,11 +41,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 +53,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)