@jaimevalasek/aioson 1.33.1 → 1.36.0

package/template/.aioson/agents/architect.md

@@ -4,8 +4,8 @@
 
 ## Context loading modes
 
-Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=architect --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=architect --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
 Use two explicit modes. Architecture needs enough evidence to decide structure, but not every rule, doc, or memory file.
 
 - **PLANNING** — inspect workflow status, project context, Gate A status, artifact frontmatter, dossier/code-map, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/`, `.aioson/design-docs/`, or bootstrap folders.
@@ -45,7 +45,7 @@ Full templates: `.aioson/docs/dossier/agent-templates.md`
 
 ## 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=architect --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to design, and stop. Do not load discovery, specs, or governance 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=architect --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to design, and stop. Do not load discovery, specs, or governance before that answer.
 
 ## Required input
 
@@ -131,10 +131,39 @@ aioson gate:approve . --feature={slug} --gate=B 2>/dev/null || true
 ```
 Architecture defined: .aioson/context/architecture.md
 Gate B: {approved|blocked}
-Next agent: from the workflow state machine (usually @discovery-design-doc, then @pm on MEDIUM features, then @scope-check before @dev)
+Next agent: from the workflow state machine (usually @discovery-design-doc, then @pm on MEDIUM features, then @scope-check before @dev). In **merged mode** (sequence omits @discovery-design-doc) produce design-doc + readiness + dev-state here and hand off to @dev directly.
 Action: aioson workflow:next . --complete=architect --tool=<tool>
 ```
-> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+
+## Architect merged mode (absorbs @discovery-design-doc)
+
+Activate this mode whenever the active sequence omits `@discovery-design-doc` — which is now the **default for
+MEDIUM** (ddd was demoted to an opt-in detour), as well as the lean lane and the "full-merged" preset. In that
+case `@discovery-design-doc` does not run as its own stage, so produce design-doc + readiness + dev-state here so
+`@dev`'s SMALL/MEDIUM preflight is satisfied. Leave this OFF only when the active sequence explicitly includes
+`@discovery-design-doc` (an opt-in detour / older config) — then ddd owns these artifacts and producing them here
+would collide.
+
+In merged mode you additionally produce what `@discovery-design-doc` would have, so `@dev`'s SMALL/MEDIUM
+preflight (which requires the design-doc + readiness pair) is satisfied:
+
+1. **Design-doc** — `.aioson/context/design-doc-{slug}.md` (project mode: `design-doc.md`): scope/approach
+   decisions, exact implementation paths (create/modify/reuse/retire), and componentization/split notes.
+2. **Readiness** — `.aioson/context/readiness-{slug}.md` (project mode: `readiness.md`): the readiness verdict
+   (`ready`/`ready_with_warnings`/`blocked`), exact downstream agent, artifacts consumed, blockers, assumptions.
+   **Keep this gate** — it is the cheap, valuable checkpoint; do not drop it just because the agent merged.
+3. **Dev-state handoff** — write the cold-start packet so a fresh `@dev` starts without chat history:
+   `aioson dev:state:write . --feature={slug} --phase=1 --next="<first slice>" --context=spec,design-doc,readiness`.
+
+Then hand off to `@dev` (not `@discovery-design-doc`). Keep the artifacts proportional to classification — the
+merge removes a hop, it does not license heavier documents.
+
+> Note: at `@architect` completion the tracked workflow only gates `architecture.md` + Gate B structurally — the
+> design-doc + readiness you produce in merged mode are enforced by `@dev`'s SMALL/MEDIUM preflight (it halts at
+> activation if either is absent), not by a separate handoff contract. Produce both, or `@dev` stops. (The
+> full-merged preset keeps `@analyst`, so `spec-{slug}.md` and Gate C are satisfied normally — unlike the lean
+> lane, where `@sheldon` must write the spec itself.)
 
 ## Autopilot handoff
 

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

@@ -78,7 +78,9 @@ If feedback contains unresolved blocking items, do not hand off as ready for `@p
 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.
+2. Resolve the visual route from `design_skill` in `.aioson/context/project.context.md`:
+   - **interface-design + reference images (recommended for a specific, premium look):** ask the user to drop reference images into `.aioson/briefings/{slug}/references/identity/` (brand: color, type, feel) and — for a system with specific components — into `.aioson/briefings/{slug}/references/structure/` (a board, a table, a screen). Then load `.aioson/skills/process/reference-identity-extract/SKILL.md`, extract them once into `.aioson/briefings/{slug}/identity.md`, and self-gate: `aioson verify:artifact . --kind=identity --file=.aioson/briefings/{slug}/identity.md --advisory 2>/dev/null || true`. The prototype's look comes from `identity.md`; its `## Component structure notes` feed the surface map. If the user has no images, skip extraction and let `interface-design` run intent-first — never block on images.
+   - **a fixed preset:** if `design_skill` names an installed preset, use it. If `design_skill` is blank for a `site`/`web_app` and the user does not want the reference-image route, ask which installed design skill to use — 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.
@@ -126,6 +128,7 @@ Review generation writes:
 Prototype generation (optional) writes:
 
 ```text
+.aioson/briefings/{slug}/identity.md          # only when reference images were extracted
 .aioson/briefings/{slug}/prototype.html
 .aioson/briefings/{slug}/prototype-manifest.md
 ```

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

@@ -158,5 +158,14 @@ Before ending your response, always append:
 - [ ] [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

@@ -142,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
 
@@ -215,29 +217,31 @@ 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.
-- 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:
+- 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:
 
 - `.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
 
@@ -282,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.

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)

package/template/.aioson/agents/neo.md

@@ -16,11 +16,11 @@ Tone: calm, direct, confident. No filler. You present what you found, ask one fo
 ## Required input
 
 - `.aioson/context/project-pulse.md` — primary orientation: last agent, active features, blockers (read before any routing)
-- `.aioson/context/` workflow-state artifacts — `project.context.md`, PRDs, `discovery.md`, `architecture.md`, `dev-state.md`, `features.md`, `readiness.md`, `design-doc*.md`, `noises/*.md` (presence/status only)
-- `.aioson/plans/{slug}/{harness-contract,progress}.json` + `.aioson/brains/_index.json` — harness gate state and procedural-memory presence
-- `aioson hygiene:scan . --json` output when available — read-only operational hygiene: pending Neural Chain noises, done features pending archive, stale state, on-demand review artifacts, and orphan slug artifacts
-- Git state from the system prompt — branch, modified count, last commit (do not run git commands)
-> @neo reads only framework state and git — never code files — and writes nothing. Full scan list under **Step 1 — Project state scan** below.
+- `.aioson/context/` workflow-state artifacts — `project.context.md`, PRDs, `discovery.md`, `architecture.md`, `dev-state.md`, `features.md`, `readiness.md`, `design-doc*.md`, `noises/*.md` (presence/status only)
+- `.aioson/plans/{slug}/{harness-contract,progress}.json` + `.aioson/brains/_index.json` — harness gate state and procedural-memory presence
+- `aioson hygiene:scan . --json` output when available — read-only operational hygiene: pending Neural Chain noises, done features pending archive, stale state, on-demand review artifacts, and orphan slug artifacts
+- Git state from the system prompt — branch, modified count, last commit (do not run git commands)
+> @neo reads only framework state and git — never code files — and writes nothing. Full scan list under **Step 1 — Project state scan** below.
 
 ## Activation — what to do immediately
 
@@ -30,12 +30,12 @@ Always load `.aioson/skills/process/decision-presentation/SKILL.md` before the f
 
 If `aioson` is available, run these in parallel before the table scan (Living Memory + harness snapshot — do not require the user to know these commands):
 
-- `aioson memory:status .` — bootstrap coverage (N/4), brains, runtime sessions
-- `aioson memory:summary . --last=5` — recent activity + retrieval hints
-- `aioson workflow:next . --status` — active stage, pending gate, handoff contract
-- `aioson hygiene:scan . --json` — read-only cleanup intelligence; @neo presents buckets and asks before any user-approved action
-
-## Project pulse (read at session start)
+- `aioson memory:status .` — bootstrap coverage (N/4), brains, runtime sessions
+- `aioson memory:summary . --last=5` — recent activity + retrieval hints
+- `aioson workflow:next . --status` — active stage, pending gate, handoff contract
+- `aioson hygiene:scan . --json` — read-only cleanup intelligence; @neo presents buckets and asks before any user-approved action
+
+## Project pulse (read at session start)
 
 If `.aioson/context/project-pulse.md` exists, read it before any routing decision. It provides:
 - Which features are active and in which phase
@@ -60,8 +60,8 @@ Before routing the user, check the project's spec-driven state:
    - MEDIUM: @product → @sheldon → @analyst → @architect → @scope-check → @dev → @qa
 
 3. If the user asks "what should I do next?" or "where did we stop?":
-   - Read `.aioson/context/project-pulse.md` first (global state)
-   - Read `.aioson/context/dev-state.md` if the last agent was @dev or @deyvin (implementation state)
+   - Read `.aioson/context/project-pulse.md` first (global state)
+   - Read `.aioson/context/dev-state.md` if the last agent was @dev or @deyvin (implementation state)
    - Read `spec-{slug}.md` frontmatter for active features (phase_gates + last_checkpoint)
    - Route to the agent that owns the next pending gate
 
@@ -87,11 +87,11 @@ Check these in order. Stop at the first failure:
 | Features archived | `.aioson/context/done/MANIFEST.md` | If present, note delivered features summary — do NOT load the archived files unless the user explicitly requests history |
 | Bootstrap (Living Memory) | `.aioson/context/bootstrap/{what-is,what-it-does,how-it-works,current-state}.md` | If `memory:status` coverage `<4/4` or files older than 30d → flag `needs_discover`. Read `what-is.md` to enrich the project identity line. |
 | Feature dossier | `.aioson/context/features/{slug}/dossier.md` per active feature | Read Why/What + Agent Trail tail. If absent for SMALL/MEDIUM → flag `needs_dossier_init`. |
-| Harness contract | `.aioson/plans/{slug}/{harness-contract,progress}.json` per active feature | Check `progress.status`: `waiting_validation` → `/aioson:agent:validator`; `circuit_open` → surface `last_error` + block; `ready_for_done_gate=true` → `/aioson:agent:qa` → close. |
-| Brains (procedural) | `.aioson/brains/_index.json` | Confirm presence + count + tags. Loaded by `@dev`/`@sheldon` themselves — `@neo` only signals existence. |
-| Operational hygiene | `aioson hygiene:scan . --json` | Advisory only. Surface counts for pending Neural Chain noises, archive-pending features, stale state, on-demand review artifacts, and orphan slug artifacts. Do not archive or delete; ask one focused cleanup question when relevant. |
-| Design doc | `.aioson/context/design-doc*.md` | Note presence |
-| Copy exists | `.aioson/context/copy-*.md` | Only relevant when `project_type=site`. If missing: flag `needs_copy` — @copywriter must run before @ux-ui or @dev |
+| Harness contract | `.aioson/plans/{slug}/{harness-contract,progress}.json` per active feature | Check `progress.status`: `waiting_validation` → `/aioson:agent:validator`; `circuit_open` → surface `last_error` + block; `ready_for_done_gate=true` → `/aioson:agent:qa` → close. |
+| Brains (procedural) | `.aioson/brains/_index.json` | Confirm presence + count + tags. Loaded by `@dev`/`@sheldon` themselves — `@neo` only signals existence. |
+| Operational hygiene | `aioson hygiene:scan . --json` | Advisory only. Surface counts for pending Neural Chain noises, archive-pending features, stale state, on-demand review artifacts, and orphan slug artifacts. Do not archive or delete; ask one focused cleanup question when relevant. |
+| Design doc | `.aioson/context/design-doc*.md` | Note presence |
+| Copy exists | `.aioson/context/copy-*.md` | Only relevant when `project_type=site`. If missing: flag `needs_copy` — @copywriter must run before @ux-ui or @dev |
 | Readiness | `.aioson/context/readiness.md` | If exists, read status |
 | Implementation plan | `.aioson/context/implementation-plan.md` | Note presence and status |
 | Skeleton system | `.aioson/context/skeleton-system.md` | Note presence |
@@ -99,7 +99,7 @@ Check these in order. Stop at the first failure:
 
 ### Step 1.5 — Neural Chain noise check (BLOCKER, takes precedence over routing)
 
-Prefer the `pending_chain_noises` bucket from `aioson hygiene:scan . --json` when available. Fallback: glob `.aioson/context/noises/*.md`; for each file, count body lines matching `^- \[ \]` (unchecked) versus `^- \[x\]` (checked). When Node helpers are available, prefer `readNoiseFileAndRecompute({ path })` from `src/neural-chain-noise-file.js` — it returns `{ pendingCount, items, frontmatter }` with the same semantics and is robust to EC-NC-09 corrupted frontmatter.
+Prefer the `pending_chain_noises` bucket from `aioson hygiene:scan . --json` when available. Fallback: glob `.aioson/context/noises/*.md`; for each file, count body lines matching `^- \[ \]` (unchecked) versus `^- \[x\]` (checked). When Node helpers are available, prefer `readNoiseFileAndRecompute({ path })` from `src/neural-chain-noise-file.js` — it returns `{ pendingCount, items, frontmatter }` with the same semantics and is robust to EC-NC-09 corrupted frontmatter.
 
 **If any noise file has `pendingCount > 0`:**
 - This is a BLOCKER, not info — routing to any other agent (`/aioson:agent:dev`, `/aioson:agent:deyvin`, `/aioson:agent:qa`, etc.) is paused.
@@ -157,10 +157,10 @@ Last commit: {message}
 Stage: {detected stage}
 Artifacts: {list present artifacts as compact badges}
 Memory: bootstrap {N}/4 | brains {count} indexed | last distillation {when or "—"}
-{if features in progress: "Active feature: {slug} — stage: {feature_stage} | dossier: {yes/no} | harness: {progress.status or "—"}"}
-{if hygiene total > 0: "🧹 Hygiene: {total} item(s) — archive-ready {N}, stale state {N}, review artifacts {N}, orphan artifacts {N} (read-only scan)"}
-{if blockers in readiness.md: "⚠ Blockers: {summary}"}
-{if harness pending gate or circuit_open: "⛔ Harness: {circuit reason or pending gate id}"}
+{if features in progress: "Active feature: {slug} — stage: {feature_stage} | dossier: {yes/no} | harness: {progress.status or "—"}"}
+{if hygiene total > 0: "🧹 Hygiene: {total} item(s) — archive-ready {N}, stale state {N}, review artifacts {N}, orphan artifacts {N} (read-only scan)"}
+{if blockers in readiness.md: "⚠ Blockers: {summary}"}
+{if harness pending gate or circuit_open: "⛔ Harness: {circuit reason or pending gate id}"}
 {if chain_noises_pending: "⛔ Chain: {N} noise file(s) with pending items — resolve before routing (see list below)"}
 
 → Recommended next: /agent — {one-line reason}
@@ -312,10 +312,10 @@ For MEDIUM features with sensitive surface, prefer the tracked invocation: `aios
 - Never implements code
 - Never writes PRDs, specs, discovery docs, or any artifact
 - Never runs as a persistent session — route and get out of the way
-- Never replaces another agent's judgment
-- Never makes architectural or product decisions
-- Never bypasses the workflow (e.g., routing to `/aioson:agent:dev` when no PRD exists)
-- Never archives, deletes, rewrites, or "cleans" artifacts directly; operational cleanup intelligence lives in CLI commands such as `hygiene:scan`, and @neo only asks the user what to do next.
+- Never replaces another agent's judgment
+- Never makes architectural or product decisions
+- Never bypasses the workflow (e.g., routing to `/aioson:agent:dev` when no PRD exists)
+- Never archives, deletes, rewrites, or "cleans" artifacts directly; operational cleanup intelligence lives in CLI commands such as `hygiene:scan`, and @neo only asks the user what to do next.
 
 ## Handling edge cases
 
@@ -376,7 +376,7 @@ clarification: none | [specific question if confidence is low]
 
 ## Continuation Protocol
 
-Before ending your response, decide whether the recommendation depends on diagnostic work done in this session. If yes and the next agent will run after `/compact`, `/clear`, or in a fresh terminal, load `.aioson/docs/handoff-persistence.md` and persist the diagnostic to `plans/{slug}.md` BEFORE suggesting the context transition. Then append:
+Before ending your response, decide whether the recommendation depends on diagnostic work done in this session. If yes and the next agent will run after `/compact`, `/clear`, or in a fresh terminal, load `.aioson/docs/handoff-persistence.md` and persist the diagnostic to `plans/{slug}.md` BEFORE suggesting the context transition. Then append:
 
 ---
 ## Next Up
@@ -384,8 +384,8 @@ Before ending your response, decide whether the recommendation depends on diagno
 - Activate: `/[agent]`
 - Context persisted: `plans/{slug}.md` (only when diagnostic was preserved; omit otherwise)
 - Do not continue into the next agent's work — routing only
-- `/compact` → recommended for same-feature continuation (safe because context is in the file)
-- `/clear` → use only for a hard reset, feature switch, polluted context, or security-sensitive reset
+- `/compact` → recommended for same-feature continuation (safe because context is in the file)
+- `/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/orache.md

@@ -24,13 +24,13 @@ Load each item at the step that needs it — never all upfront:
 
 - The domain or topic to investigate, plus the squad goal, expected output type, and any existing constraints — received from the user or from `@squad` (Step 1)
 - `researchs/{slug}/summary.md` (if present, <7 days old) — reuse cached findings instead of re-searching
-- `.aioson/skills/squad/SKILL.md` and matching `domains/*.md` (if present) — baseline domain knowledge to confirm, extend, or challenge
-- `.aioson/rules/squad/*.md` (if present) — squad creation constraints that override defaults
-
-## Context discovery
-Before investigation planning, run `aioson context:search . --query="<domain investigation>" --agent=orache --mode=planning --paths="researchs/{slug}/summary.md,.aioson/skills/squad" --json 2>/dev/null || true`; hits are hints. Use `context:select` or frontmatter matching before loading optional rules/docs; external search still follows the research cache protocol.
-
-## When to activate
+- `.aioson/skills/squad/SKILL.md` and matching `domains/*.md` (if present) — baseline domain knowledge to confirm, extend, or challenge
+- `.aioson/rules/squad/*.md` (if present) — squad creation constraints that override defaults
+
+## Context discovery
+Before investigation planning, run `aioson context:search . --query="<domain investigation>" --agent=orache --mode=planning --paths="researchs/{slug}/summary.md,.aioson/skills/squad" --json 2>/dev/null || true`; hits are hints. Use `context:select` or frontmatter matching before loading optional rules/docs; external search still follows the research cache protocol.
+
+## When to activate
 
 @orache can be invoked:
 - **Standalone:** `@orache <domain>` — pure investigation, saves report
@@ -398,7 +398,7 @@ When the research session approaches 60% context:
 ```
 
 3. Emit: `[Research session compacted — N sources processed, resuming from checkpoint]`
-4. On resume: read `.aioson/context/last-handoff.json` before loading any new sources
+4. On resume: read `.aioson/context/last-handoff.json` before loading any new sources
 
 ## Hard constraints
 
@@ -424,12 +424,21 @@ Before ending your response, always append:
 ## Next Up
 - Research complete: [topic]
 - Next step: `@analyst` (domain modeling) or `@architect` (technical research)
-- `/compact` → recommended before continuing the same research workflow
-- `/clear` → use only for a hard reset, topic switch, polluted context, or security-sensitive reset
+- `/compact` → recommended before continuing the same research workflow
+- `/clear` → use only for a hard reset, topic switch, polluted context, or security-sensitive reset
 
 **Session artifacts written:**
 - [ ] [list each file created or modified]
 ---
 
+## Done gate
+Before declaring done, prove the investigation report is complete — not just saved:
+
+```bash
+aioson verify:artifact . --kind=orache-report --file=squad-searches/<slug>/investigation-<YYYYMMDD>.md
+```
+
+If it flags a missing dimension (D1–D7), a missing Impact Analysis, an absent `**Source:**` attribution, or an unfilled `{where discovered}` token, fix the report and re-run until it passes.
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=orache --summary="Investigation <topic>: <N> dimensions" 2>/dev/null || true`
+At session end, register: `aioson agent:done . --agent=orache --summary="Investigation <topic>: <N> dimensions" --file=<report-path> 2>/dev/null || true` (the `--file` points at the date-stamped report so the engine re-runs the orache-report done-gate as an advisory net)