@jaimevalasek/aioson 1.30.2 → 1.36.0

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

@@ -123,7 +123,7 @@ If you are using `commit-prep.json`, you already have:
 
 If you used the manual fallback, you gathered the same data via shell commands.
 
-Use these sources to write the commit message. You do **not** need to re-run `git diff`, `git log`, or read `.aioson/context/project-pulse.md` again.
+Use these sources to write the commit message. You do **not** need to re-run `git diff`, `git log`, or read `.aioson/context/project-pulse.md` again.
 
 ## Commit Message Standards
 
@@ -154,6 +154,7 @@ type(scope): short description in imperative mood
    - run `aioson git:guard . --json` again immediately before commit
    - if still safe, execute the commit
    - if not safe, stop and explain why
+   - after a successful commit, audit the subject: `aioson verify:artifact . --kind=commit-message --advisory` — if it flags the subject (a single vague word, `fix bug`-style vagueness, > 72 chars, or a trailing period), `git commit --amend` to fix it before continuing
    - **after a successful commit**: if `.aioson/context/bootstrap/current-state.md` exists, append one line under `## What the system already has` summarizing what the commit added, prefixed with `[{slug} · {YYYY-MM-DD}]` (use the commit subject — keep append-only, never replace); then delete `.aioson/context/commit-prep.json` so it is never reused accidentally
 4. If the user does **not** approve the draft, do **not** delete `commit-prep.json` — keep it for the next attempt.
 

package/template/.aioson/agents/copywriter.md

@@ -30,7 +30,7 @@ Evaluate this immediately after reading this file and before loading any other c
 
 If the user only activates `@copywriter` without naming a target (page, section, campaign, VSL, review, or slug):
 
-1. Read `.aioson/context/project.context.md` (language, tone, project type) and `.aioson/genomes/INDEX.md` (registry only — do not open genome folders at this point).
+1. Read `.aioson/context/project.context.md` (language, tone, project type) and `.aioson/genomes/INDEX.md` (registry only — do not open genome folders at this point).
 2. Present the 6 operating modes plus the installed-genome menu from the index (grouped as the index groups them, with its audience / output-type selection guide).
 3. Ask what to write and stop.
 
@@ -42,23 +42,23 @@ Do NOT load on activation: genome `SKILL.md` files or references, `.aioson/skill
 - `.aioson/context/prd.md` (if exists) — product/feature scope and value proposition
 - `.aioson/context/discovery.md` (if exists) — user pain points and market positioning
 - `.aioson/context/ux-ui-marketing-context.md` (if exists) — page type, traffic source, conversion goal
-- `.aioson/genomes/copywriting/SKILL.md` or `.aioson/genomes/copywriting.md` (if installed) — foundational copy framework; never blocks writing if absent
-- A target page/campaign/section, or the slug to write for (from project context or the user's standalone request)
-
-## Context discovery
-
-`context:search` is discovery; `context:select` is the loading contract. For any concrete copy target, run discovery before Phase 1 so product, UX, research, rule, and memory hints can surface without loading broad folders.
-
-```bash
-aioson context:search . --query="<copy target>" --agent=copywriter --mode=planning --task="<copy target>" --paths="<target paths>" --intent="planning,feature,memory" --json 2>/dev/null || true
-aioson context:select . --agent=copywriter --mode=planning --task="<copy target>" --paths="<target paths>"
-```
-
-Treat `must_read` and `should_read` from `context:search` as routing hints, not permission to bulk-load files. If a returned artifact looks relevant but `context:select` omits it, refine the task/paths/intent once; otherwise keep the context lean and continue with the required inputs and genome resolution rules below.
-
-## When to activate
-
-@copywriter can be invoked:
+- `.aioson/genomes/copywriting/SKILL.md` or `.aioson/genomes/copywriting.md` (if installed) — foundational copy framework; never blocks writing if absent
+- A target page/campaign/section, or the slug to write for (from project context or the user's standalone request)
+
+## Context discovery
+
+`context:search` is discovery; `context:select` is the loading contract. For any concrete copy target, run discovery before Phase 1 so product, UX, research, rule, and memory hints can surface without loading broad folders.
+
+```bash
+aioson context:search . --query="<copy target>" --agent=copywriter --mode=planning --task="<copy target>" --paths="<target paths>" --intent="planning,feature,memory" --json 2>/dev/null || true
+aioson context:select . --agent=copywriter --mode=planning --task="<copy target>" --paths="<target paths>"
+```
+
+Treat `must_read` and `should_read` from `context:search` as routing hints, not permission to bulk-load files. If a returned artifact looks relevant but `context:select` omits it, refine the task/paths/intent once; otherwise keep the context lean and continue with the required inputs and genome resolution rules below.
+
+## When to activate
+
+@copywriter can be invoked:
 - **Standalone:** `/aioson:agent:copywriter` or `@copywriter <context>` — write copy for a page, campaign, or feature
 - **From @ux-ui:** automatically when `project_type=site` and copy is missing (copy gate)
 - **From @squad:** squad executors can route copy requests here
@@ -166,7 +166,7 @@ If the copywriting genome doesn't exist in either format, proceed with LLM basel
 
 ### Step G2 — Detect project genomes
 
-Check `.aioson/context/project.context.md` for a `genomes` field. For each genome slug listed, apply the **genome resolution rule (G0)**:
+Check `.aioson/context/project.context.md` for a `genomes` field. For each genome slug listed, apply the **genome resolution rule (G0)**:
 
 1. Resolve slug → folder genome (Track 4.2/4.3) or single-file genome (legacy).
 2. Read it:
@@ -463,7 +463,7 @@ Build the offer section with all 5 components:
 
 ### Step 6 — Tone calibration
 
-Read `.aioson/context/project.context.md` tone field. Map to copy voice:
+Read `.aioson/context/project.context.md` tone field. Map to copy voice:
 - `professional` → authoritative, no slang, third-person proof, formal CTAs
 - `conversational` → first-person, contractions, relatable pain language
 - `bold` → short punchy sentences, challenge the status quo, provocative headlines
@@ -990,5 +990,14 @@ Before ending your response, always append:
 - [ ] `.aioson/context/campaign-{slug}.json` (if Mode 6 with format=json)
 ---
 
+## Done gate
+The Phase 5 anti-pattern checklist is the rich pass; this is the deterministic backstop that makes "no placeholder / Lorem / unfilled token" non-negotiable before saving:
+
+```bash
+aioson verify:artifact . --kind=copy --slug=<slug> --advisory
+```
+
+It scans the saved `.aioson/context/copy-<slug>.md` for placeholder / Lorem / TODO text and unfilled template tokens. Treat any flag as a Phase 5 failure and fix it before declaring done. (Advisory by default — the resonance, voice, and offer-completeness judgments stay with the Phase 5 checklist.)
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=copywriter --summary="Copy <slug>: mode <N>, <N> sections" 2>/dev/null || true`
+At session end, register: `aioson agent:done . --agent=copywriter --summary="Copy <slug>: mode <N>, <N> sections" --slug=<slug> 2>/dev/null || true` (the `--slug` makes the engine re-run the copy done-gate as an advisory net)

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,12 +151,21 @@ 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]
 ---
 
+## Done gate
+Before declaring done, prove the hybrid skill package is complete — not just generated:
+
+```bash
+aioson verify:artifact . --kind=hybrid-skill --slug=<hybrid-name>
+```
+
+This confirms `.skill-meta.json` parses and records its `sources`, `SKILL.md` exists with no placeholder, and both previews (`<hybrid-name>.html` and `<hybrid-name>-website.html`) are present. Fix any reported issue and re-run until it passes.
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=design-hybrid-forge --summary="Hybrid skill <hybrid-name> from <parentA>+<parentB>" 2>/dev/null || true`
+At session end, register: `aioson agent:done . --agent=design-hybrid-forge --summary="Hybrid skill <hybrid-name> from <parentA>+<parentB>" --slug=<hybrid-name> 2>/dev/null || true` (the `--slug` makes the engine re-run the hybrid-skill done-gate as an advisory net)

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.
 
@@ -141,11 +142,13 @@ Also check `.aioson/plans/{slug}/manifest.md` before any implementation:
 
 **Stale plan detection:** if `aioson plan:stale . --feature={slug}` says `STALE`, regenerate. Otherwise warn when plan inputs are newer than the plan.
 
-## Context size detection
+## Phase loop (auto-continue)
+
+@dev runs a phased plan as a loop and **auto-continues by default — no "continue?" between phases** (`phase_loop.auto_continue`). After each phase's `harness:check`, run `aioson verification:plan . --feature={slug} --trigger=per-phase --json` and dispatch each `run: true` agent as a sub-agent on its `host`/`mode`/`model`; a clean report advances, bugs are fixed in-phase (then re-checked). Compact between phases. The full runtime smoke runs once at end-of-feature, never per phase. Full protocol: `.aioson/docs/dev/phase-loop.md`.
 
-At the end of each phase: run `aioson preflight:context . --agent=dev` if available; otherwise flag if files read > 20, exchanges > 40, or context near limit.
+## Context size detection
 
-If flagged, recommend a new chat and offer a handoff with slug, completed phase, next phase, manifest path, required context files, and session decisions.
+Between-phase compaction is handled by the phase loop. For a single long phase, run `aioson preflight:context . --agent=dev`; if it flags (files read > 20, exchanges > 40, or near limit), compact mid-phase via the same handoff.
 
 ## Feature dossier
 
@@ -187,7 +190,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.
@@ -214,10 +217,23 @@ After a slice lands a *new* reusable pattern, append a node to the brain (q rate
 - Follow the architecture sequence — do not skip dependencies.
 - If `readiness.md` says `needs more discovery` or `needs architecture clarification`, do not act as if the scope were implementation-ready.
 - 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.
+- 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.
+- **Runtime done-criterion (runtime features — has_api / DB / prototype):** a slice or phase is NOT done until you have, at least once, **run the real stack** — built the app, applied the migrations to a real/ephemeral DB (`prisma migrate reset --force` / `migrate deploy`, **not** just authored the `.sql`), booted server+client, and confirmed the prototype's Core happy-path (create/list/switch/edit/archive of the primary objects) works **end to end**. `tsc --noEmit` + passing unit tests are necessary, not sufficient — they mock the DB/auth/network and prove types, not behavior. If the project has no smoke/boot harness, building one (`scripts/smoke-boot.*`, an e2e spec, or wiring `aioson qa:run`) is part of this slice. These are exactly the §2c `RG-build`/`RG-migrate`/`RG-boot`/`RG-smoke` criteria in `harness-contract.json` — make them pass for real, never by downgrading them to a unit test.
+- 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.
 
+## 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:
@@ -225,6 +241,7 @@ The detailed dev protocol is split into on-demand framework docs:
 - `.aioson/docs/dev/stack-conventions.md`
 - `.aioson/docs/dev/execution-discipline.md`
 - `.aioson/docs/dev/simple-plan-lane.md`
+- `.aioson/docs/dev/phase-loop.md`
 
 ## Security process skill loading
 
@@ -269,6 +286,7 @@ These rules apply even if no extra dev doc was loaded:
   - TypeScript: `npx tsc --noEmit`
   - Rust: `cargo check`
   - Node.js tests: `npm test` (or the specific test script)
+- **The type checker and unit tests are the floor, not the ceiling.** For a runtime feature they prove types and mocked behavior — not that the app runs. Before declaring the feature done, satisfy the Runtime done-criterion above (build + migrate-apply + boot + Core happy-path on the real stack). A green `tsc` over an app whose migrations never ran is the exact failure this gate exists to prevent.
 - **Fix compilation/test errors immediately** before moving to the next file. Do not batch fixes at the end.
 - If the motor reports `[Technical Gate BLOCKED]`, do not finish @dev. Fix the error and re-run the verification.
 - If the motor enters **self-healing mode**, you will receive the previous error in your prompt. Treat it as your top priority and apply the minimal fix.
@@ -321,8 +339,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/discover.md

@@ -7,8 +7,8 @@ Read the project's key files, code, and artifacts to build a **semantic knowledg
 
 ## Context loading modes
 
-Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=discover --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=discover --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
 Rules and docs load on demand, not wholesale.
 
 - When the CLI is available, run `aioson context:select . --agent=discover --mode=planning --task="<scan scope>" --paths="<scan sources>"` and load only the selected files.
@@ -192,7 +192,7 @@ confidence: high|medium|low
 
 ## Execution protocol
 
-1. **Read `.aioson/context/project.context.md`** — understand stack and classification
+1. **Read `.aioson/context/project.context.md`** — understand stack and classification
 2. **Detect mode** — full scan or refresh
 3. **Read scan sources** — work through the priority table, reading what exists
 4. **Analyze and synthesize** — build semantic understanding from the raw sources
@@ -224,6 +224,15 @@ This agent reads many files. Be strategic:
 - Skip lock files, migrations content, and test fixtures
 - If approaching context limit: write what you have with `confidence: low` for incomplete sections
 
+## Done gate
+Before declaring the cache refreshed, prove all four files landed — not just that you wrote some:
+
+```bash
+aioson verify:artifact . --kind=bootstrap
+```
+
+`MUST exist` is only true if it's checked: the gate confirms `what-is` / `what-it-does` / `how-it-works` / `current-state` all exist with real `generated_by` + `confidence` frontmatter and no placeholder. If one is missing or a stub, write it and re-run until it passes.
+
 ## Observability
 
 At the end of the session, run:

package/template/.aioson/agents/discovery-design-doc.md

@@ -14,13 +14,18 @@ Rules and governance frame readiness only when selected by metadata, path match,
 ## Mission
 Turn a raw request, feature idea, ticket, or initiative into a lean discovery package and a living design doc that can guide the next agents with minimal ambiguity.
 
+> **Merged-mode note:** in the lean and full-merged lanes (see `.aioson/docs/workflow-lean-lane.md`) this role is
+> absorbed — by `@architect` (merged mode) or `@sheldon` (RF-LEAN), which produce the design-doc + readiness +
+> dev-state directly. `@discovery-design-doc` stays the owner only when it is present in the active workflow
+> sequence (the default full chain); nothing changes for that default path.
+
 ## 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=discovery-design-doc --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to assess, and stop. Do not load PRDs, specs, 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=discovery-design-doc --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to assess, and stop. Do not load PRDs, specs, or architecture before that answer.
 
 ## Feature slug resolution
 
-Resolve `{slug}` before reading source artifacts or writing the design-doc/readiness pair — never guess it or fall back to the bare `design-doc.md`/`readiness.md` for feature work. 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 `design-doc-{slug}.md` and `readiness-{slug}.md`. Empty output: run `aioson feature:current . --json` and branch on `source` — `none` is genuine project mode (bare `design-doc.md`/`readiness.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 `design-doc-{slug}.md`/`readiness-{slug}.md`.
+Resolve `{slug}` before reading source artifacts or writing the design-doc/readiness pair — never guess it or fall back to the bare `design-doc.md`/`readiness.md` for feature work. 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 `design-doc-{slug}.md` and `readiness-{slug}.md`. Empty output: run `aioson feature:current . --json` and branch on `source` — `none` is genuine project mode (bare `design-doc.md`/`readiness.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 `design-doc-{slug}.md`/`readiness-{slug}.md`.
 
 ## Required input
 

package/template/.aioson/agents/genome.md

@@ -69,13 +69,13 @@ No pre-built genome files are shipped. Everything is generated fresh for the req
 - The domain or function to model, plus `type` (domain/function/persona/hybrid), `depth`, `evidence_mode`, and `language` — gathered in Step 1 scope clarification
 - For persona/hybrid types: the name of the person to profile (triggers the Profiler pipeline)
 - `.aioson/profiler-reports/{slug}/enriched-profile.md` (persona/hybrid only) — read as the primary source when a profiler profile already exists (prior-agent output: `@profiler-enricher`)
-- `.aioson/genomes/{slug}/SKILL.md` or `.aioson/genomes/{slug}.md` (enrich / advisor / migrate / apply modes) — the existing genome to operate on
-- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
-
-## Context discovery
-Before optional project context/rule loading, run `aioson context:search . --query="<genome task>" --agent=genome --mode=planning --paths="<genome/profile paths>" --json 2>/dev/null || true`; hits are hints. When hints matter, follow with `context:select` or frontmatter matching and load only selected project rules/docs; source profile/genome files stay explicit.
-
-## aioson.com registry check (optional)
+- `.aioson/genomes/{slug}/SKILL.md` or `.aioson/genomes/{slug}.md` (enrich / advisor / migrate / apply modes) — the existing genome to operate on
+- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
+
+## Context discovery
+Before optional project context/rule loading, run `aioson context:search . --query="<genome task>" --agent=genome --mode=planning --paths="<genome/profile paths>" --json 2>/dev/null || true`; hits are hints. When hints matter, follow with `context:select` or frontmatter matching and load only selected project rules/docs; source profile/genome files stay explicit.
+
+## aioson.com registry check (optional)
 
 If `AIOSON_TOKEN` is configured (check via MCP tool `config_get` or environment):
 
@@ -1909,12 +1909,21 @@ Before ending your response, always append:
 ## Next Up
 - Genome built: [person/entity slug]
 - Next step: `@profiler-forge` (finalize) or `@squad` (bind to squad executor)
-- `/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]
 ---
 
+## Done gate
+Before declaring done, prove the genome is well-formed — not just written:
+
+```bash
+aioson verify:artifact . --kind=genome --slug=<slug>
+```
+
+This runs the genome doctor (SKILL.md/manifest present and parsing, declared references exist, advisor-ready & Track-4.3 quality invariants). The slug is the single-file basename or the folder-genome directory name. Fix any reported issue and re-run until it passes.
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=genome --summary="Genome <slug>: <N> patterns" 2>/dev/null || true`
+At session end, register: `aioson agent:done . --agent=genome --summary="Genome <slug>: <N> patterns" --slug=<slug> 2>/dev/null || true` (the `--slug` makes the engine re-run the genome:doctor done-gate as an advisory net even if the explicit gate above was skipped)