@jaimevalasek/aioson 1.33.1 → 1.37.0

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

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

package/template/.aioson/agents/tester.md

@@ -4,6 +4,10 @@
 
 > ⚡ **ACTIVATED** — You are now operating as @tester. Execute the instructions in this file immediately.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @tester` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Produce an engineering-grade test suite for already-implemented applications.
 Do not implement features. Do not review the product. Test what exists.

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

@@ -24,7 +24,8 @@ Rules and design docs override this file only when selected by metadata, operati
 4. If `project_type=site` and the operation produces HTML, also read `.aioson/skills/static/static-html-patterns.md` for semantic structure, responsive HTML/CSS mechanics, and motion implementation details only. Never treat it as a second visual system.
 5. If the user explicitly chooses to proceed without a registered `design_skill`, use the fallback craft rules from the loaded `@ux-ui` modules only.
 6. **ABSOLUTE RULE — ONE SKILL ONLY:** When `design_skill` is set, load **exclusively** `.aioson/skills/design/{design_skill}/SKILL.md` and the references it specifies. Loading or mixing any other design skill is forbidden.
-7. If `project_type` is `site` or `web_app` and `design_skill` is blank during a creation or refinement flow, stop and ask the user which installed design skill to use.
+6a. **`identity.md` is an INPUT to the one skill — never a second skill.** When `design_skill: interface-design` and an `identity.md` exists (`.aioson/briefings/{slug}/identity.md`, else `.aioson/context/identity.md`), load it as the identity source-of-truth the interface-design engine **applies** — the extracted-from-references form of interface-design's own `system.md` (see `.aioson/docs/reference-identity.md`). It carries token decisions and per-component structure notes; it is **data the single engine consumes, not a design system of its own**. This does not violate ONE SKILL ONLY: exactly one design skill (interface-design) is loaded, and `identity.md` parameterizes it. Never load `identity.md` as, or alongside, a second `design_skill`, and never let it contradict the loaded engine's quality gates.
+7. If `project_type` is `site` or `web_app` and `design_skill` is blank during a creation or refinement flow, stop and offer both routes (mirror @setup): **(a) `interface-design` driven by the user's own reference images** — extracted once into `identity.md` via `.aioson/skills/process/reference-identity-extract/SKILL.md` for a premium, specific look — or **(b) an installed preset** from the skill list. Do not auto-pick either.
 
 ## Step 0.5 — Copy gate (sites only)
 

package/template/.aioson/agents/validator.md

@@ -36,6 +36,7 @@ To preserve impartiality and avoid continuity hallucinations, you operate in a *
    - `.aioson/plans/{slug}/progress.json` (current state)
    - Files explicitly listed in `progress.json.completed_steps`
    - Output of diagnostic tools (linters, test runners, compilers)
+   - `manifest.json` and `.aioson/briefings/{slug}/prototype-manifest.md` — **only** for the Step 0 contract-integrity precheck (to read the runtime surface and the Core interaction list). Not for judging the product, the design, or whether a feature "should" exist — strictly to confirm the contract is well-formed for the feature's surface.
 2. **NEVER read:**
    - Conversation history from other agents (`@dev`, `@analyst`, `@architect`)
    - PRDs, requirements, or architecture docs (your focus is the binary contract, not product vision)
@@ -47,6 +48,36 @@ To preserve impartiality and avoid continuity hallucinations, you operate in a *
 
 ## Execution protocol (RF-VAL)
 
+### Step 0 — Contract-integrity precheck (runtime features)
+
+Before scoring anything, confirm the contract is **capable** of proving the app works. A contract you cannot
+fail through is worthless: a feature can pass every unit test while its migrations never applied, its UI was
+never wired, and the process never booted. This precheck is the one thing that lets a blind executor catch
+that class of failure — it checks the **contract's shape**, never the product's merit.
+
+1. Determine whether the feature is a **runtime feature**: read `manifest.json` — `has_api: true`, a declared
+   server/process, or a Play runtime ⇒ yes. A Prisma schema / migrations folder in `completed_steps` ⇒ yes. A
+   `## Prototype reference` (a `prototype-manifest.md` with Core interactions) ⇒ yes.
+2. If it **is** a runtime feature, the contract MUST contain at least the runtime-gate criteria from
+   `harness-contract.md` §2c — `RG-build`, `RG-migrate`, `RG-boot`, `RG-smoke` (or equivalents whose
+   `verification` actually builds, applies migrations to a real DB, boots the process, and drives the Core
+   happy-path end to end). Also reject the contract if **two binary criteria share an identical `verification`
+   command** (padding) or if every criterion is a unit/component test (`*.test.*` only).
+3. **If the contract is missing the runtime gate (or is padded), STOP.** Do not score the unit criteria green.
+   Emit the verdict with `overall_score: 0`, `ready_for_done_gate: false`, and a `results` entry:
+   `{ "id": "contract-integrity", "passed": false, "reason": "Runtime feature but harness-contract has no RG-build/RG-migrate/RG-boot/RG-smoke (or contains duplicate/all-unit verification). The app's build, migrations, boot and Core happy-path are unverified. Route back to @sheldon to add §2c runtime-gate criteria, then re-run @dev." }`.
+   This is not a product judgment — it is a statement that the contract cannot prove the feature runs.
+4. If the feature is **not** a runtime feature, or the runtime gate is present and non-duplicated, continue to
+   Step 1 normally.
+
+> **Deterministic backstop.** `aioson harness:check . --slug={slug} --json` already enforces the detectable
+> subset of this precheck: its `integrity` block returns `missing_runtime_gate` / `duplicate_verification` and
+> sets `ok: false` whenever it can locate the runtime surface (prototype-manifest or a migration step). Read it
+> and copy a deterministic integrity failure straight into your verdict. Your judgment is still required for the
+> two things the CLI cannot prove: a Play `has_api` runtime whose `manifest.json` is not framework-locatable,
+> and whether an `RG-smoke` criterion *actually* drives the Core happy-path rather than being a unit test
+> wearing the `RG-` id.
+
 ### Step 1 — Load
 Locate `harness-contract.json` for the current feature. Identify criteria with `binary: true`.
 
@@ -117,7 +148,8 @@ At session end, register: `aioson agent:epilogue . --agent=validator --feature=<
 ## Autopilot handoff (post-dev cycle)
 
 When `auto_handoff: true` is set in `project.context.md`, after the verdict and `agent:epilogue`/`agent:done` (`.aioson/docs/autopilot-handoff.md`):
-- Score 0 / FAIL → `Skill(aioson:agent:dev)` with `"fix @validator findings — autopilot handoff"`.
+- **Contract-integrity fail (Step 0)** → `Skill(aioson:agent:sheldon)` with `"add §2c runtime-gate criteria to harness-contract — @validator contract-integrity fail"`. The contract is the problem, not the code; do not route to `@dev` yet.
+- Score 0 / FAIL (a real criterion failed) → `Skill(aioson:agent:dev)` with `"fix @validator findings — autopilot handoff"`.
 - Score 1 / PASS → **STOP**. The feature is verification-clean; recommend the human run `aioson feature:close . --feature={slug}`. **Never auto-run `feature:close`** — the close is the human gate.
 
 Emit `Autopilot: @validator → invoking @<next> (Ctrl+C to interrupt)` before invoking. If `auto_handoff` is absent or `false`, hand off manually.

package/template/.aioson/config/verification.json

@@ -0,0 +1,61 @@
+{
+  "version": "1.0",
+  "host": "auto",
+  "agents": {
+    "qa": {
+      "enabled": true,
+      "triggers": ["per-phase", "end-of-feature"],
+      "dispatch": {
+        "claude": { "mode": "native", "model": "sonnet-4.6" },
+        "codex": { "mode": "native", "model": "configured-default" },
+        "opencode": { "mode": "native", "model": "configured-default" }
+      },
+      "report": "qa-report-{slug}.md"
+    },
+    "tester": {
+      "enabled": "auto",
+      "triggers": ["end-of-feature"],
+      "dispatch": {
+        "claude": { "mode": "native", "model": "sonnet-4.6" },
+        "codex": { "mode": "native", "model": "configured-default" },
+        "opencode": { "mode": "native", "model": "configured-default" }
+      },
+      "report": "test-report-{slug}.md"
+    },
+    "pentester": {
+      "enabled": "auto",
+      "triggers": ["sensitive-surface", "end-of-feature"],
+      "dispatch": {
+        "claude": { "mode": "native", "model": "opus-4.8" },
+        "codex": { "mode": "native", "model": "configured-default" },
+        "opencode": { "mode": "native", "model": "configured-default" }
+      },
+      "report": "security-findings-{slug}.json"
+    },
+    "validator": {
+      "enabled": true,
+      "triggers": ["end-of-feature"],
+      "dispatch": {
+        "claude": { "mode": "native", "model": "opus-4.8" },
+        "codex": { "mode": "native", "model": "configured-default" },
+        "opencode": { "mode": "native", "model": "configured-default" }
+      },
+      "cross_check": { "enabled": false, "mode": "external", "tool": "codex", "model": "configured-default" },
+      "report": "validator-report-{slug}.json"
+    }
+  },
+  "budget": {
+    "max_subagents_per_phase": 1,
+    "skip_on_micro": true,
+    "full_smoke": "end-of-feature-only"
+  },
+  "phase_loop": {
+    "auto_continue": true,
+    "compact_between_phases": true,
+    "max_fix_retries_per_phase": 2
+  },
+  "audit_code": {
+    "tracked_gate": "advisory",
+    "scope": "changed"
+  }
+}

package/template/.aioson/config.md

@@ -8,8 +8,12 @@
 
 ## Project sizes
 - MICRO: `@setup -> @product (optional) -> @dev`
-- SMALL: `@setup -> @product -> @analyst -> @scope-check(pre-dev) -> @architect -> @discovery-design-doc -> @dev -> @qa`
-- MEDIUM: `@setup -> @product -> @analyst -> @architect -> @discovery-design-doc -> @ux-ui -> @pm -> @orchestrator -> @scope-check(pre-dev) -> @dev -> @qa`
+- SMALL: `@setup -> @product -> @sheldon -> @dev -> @qa` (lean by default — `@sheldon` is the single spec authority)
+- MEDIUM: `@setup -> @product -> @orchestrator -> @dev -> @qa` (project); a MEDIUM **feature** runs `@product -> @orchestrator -> @dev -> @pentester -> @qa`. `@orchestrator` is the MEDIUM single spec authority (the "maestro") — it fans out to `@analyst` + `@architect` + `@pm` (+ `@ux-ui` when UI-heavy) as sub-agents and consolidates their work into one gated spec package for `@dev`.
+
+> `@analyst`, `@architect`, `@pm`, `@discovery-design-doc`, `@scope-check(pre-dev)`, and `@ux-ui` are no longer default-chain hops — `@orchestrator` invokes them as sub-agents in the MEDIUM maestro lane, and they remain available as opt-in detours. `@architect` runs in **merged mode** (design-doc + readiness + dev-state) only on the opt-in full-chain detour that routes `@architect -> @dev` while omitting `@discovery-design-doc`. The deterministic drift check (`spec:analyze`) now runs at the `@dev`/`@qa` done gate (`finalizeCurrentStage`), not as a separate agent hop.
+
+**Lean lane (SMALL default; opt-in for MEDIUM):** `@sheldon` is the single spec authority — `@product -> @sheldon -> @dev -> @qa` (with a `@validator` detour when a harness contract exists). SMALL runs this by default; MEDIUM defaults to the `@orchestrator` maestro lane (the horizontal fan-out counterpart) but can opt into the `@sheldon` lean shape by dropping the lean preset into `.aioson/context/workflow.config.json`. Full guide in `.aioson/docs/workflow-lean-lane.md`. The **runtime smoke gate** (build + migrate + boot + Core happy-path on the real stack, `harness-contract.md` §2c) is mandatory in **both** lanes — neither closes a runtime feature without running the real app.
 
 Optional alignment checkpoints:
 - After `@dev`: `@scope-check --scope-mode=post-dev` when the implementation changed planned behavior, touched unexpected files, or skipped approved scope.
@@ -41,7 +45,7 @@ Setting: `context_warning_threshold` (default: 65%)
 
 When an agent notices it is close to the threshold:
 1. Write all in-progress artifacts to disk (disk-first)
-2. Emit this warning in the selected project language: "Context at {X}% — I recommend `/compact` before the next phase; use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset"
+2. Emit this warning in the selected project language: "Context at {X}% — I recommend `/compact` before the next phase; use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset"
 3. Include the current work in `last_checkpoint`
 
 ## Context contract
@@ -63,7 +67,7 @@ Optional testing fields:
 - `test_runner` (for example `pest`, `jest`, `vitest`, `pytest`, `rspec`, `foundry`)
 
 Optional workflow fields:
-- `auto_handoff` (boolean, default `false`) — when `true`, the feature-workflow agents from `@analyst` up to the `@dev` handoff (including `@pm` on MEDIUM features) chain automatically via skill auto-invocation instead of stopping for manual activation. Protocol and stop conditions: `.aioson/docs/autopilot-handoff.md`. Upstream agents (`@briefing`, `@product`, `@sheldon`) always hand off manually.
+- `auto_handoff` (boolean, default `false`) — when `true`, the deterministic pre-dev feature-workflow agents chain automatically via skill auto-invocation up to the `@dev` handoff instead of stopping for manual activation. Protocol and stop conditions: `.aioson/docs/autopilot-handoff.md`. Upstream agents (`@briefing`, `@product`, `@sheldon`, `@orchestrator`) always hand off manually — so neither the SMALL lean default nor the MEDIUM maestro default has pre-dev hops to auto-chain. `@analyst`, `@architect`, `@pm`, `@discovery-design-doc`, `@scope-check`, and `@ux-ui` auto-chain only as opt-in detours when present in the active sequence.
 
 Allowed `project_type` values:
 - `web_app`
@@ -229,7 +233,7 @@ Default governance files:
 
 ### Design docs (`.aioson/context/design-doc.md`)
 
-Living decision documents that bridge discovery and implementation. Produced by `@discovery-design-doc`.
+Living decision documents that bridge discovery and implementation. Produced by `@orchestrator` (maestro mode) on MEDIUM and `@sheldon` on the SMALL lean lane by default; by `@architect` (merged mode) or `@discovery-design-doc` when those opt-in detours are in the sequence.
 
 ```markdown
 ---
@@ -243,7 +247,7 @@ agents: [dev, architect]   # empty [] = all agents load it
 
 | | PRD (`prd.md`) | Code governance (`.aioson/design-docs/`) | Design doc (`design-doc.md`) |
 |---|---|---|---|
-| **Produced by** | `@product` | Installer + project team | `@discovery-design-doc` |
+| **Produced by** | `@product` | Installer + project team | `@orchestrator` maestro / `@sheldon` lean (`@architect` merged or `@discovery-design-doc` detour) |
 | **Focus** | What and why — vision, users, problem, features | Structural code quality rules | How — technical flows, decisions, risks, slices |
 | **Audience** | All agents | Agents doing structural planning or implementation | Technical agents (dev, architect, qa) |
 | **Lifecycle** | Written once, enhanced by @pm | Stable, edited when conventions change | Living document, updated as decisions are made |
@@ -275,12 +279,12 @@ AIOSON ships three types of skills in `.aioson/skills/`:
 | **Design skills** | `.aioson/skills/design/` | Explicit — via `design_skill` in project.context.md. Only ONE can be active. |
 | **Static skills** | `.aioson/skills/static/` | Automatic — agents match by `framework` in project.context.md |
 | **Dynamic skills** | `.aioson/skills/dynamic/` | Automatic — agents load when task references external services |
-| **Process skills** | `.aioson/skills/process/` | Loaded on demand when an agent needs a workflow method such as SDD, decision presentation, prompt sharpening, feature expansion, or design-skill creation |
+| **Process skills** | `.aioson/skills/process/` | Loaded on demand when an agent needs a workflow method such as SDD, decision presentation, prompt sharpening, feature expansion, or design-skill creation |
 
 First-party process skills include:
 
-- `prompt-sharpener` — improves agent prompts, skills, PRDs, plans, and handoffs by turning vague guidance into evidence-driven decision behavior while preserving workflow contracts.
-- `briefing-expansion-scout`, `product-scope-expansion`, `sheldon-expansion-audit` — enrich feature thinking only when a rich surface or prior expansion artifact justifies it, using `.aioson/docs/feature-expansion-taxonomy.md`.
+- `prompt-sharpener` — improves agent prompts, skills, PRDs, plans, and handoffs by turning vague guidance into evidence-driven decision behavior while preserving workflow contracts.
+- `briefing-expansion-scout`, `product-scope-expansion`, `sheldon-expansion-audit` — enrich feature thinking only when a rich surface or prior expansion artifact justifies it, using `.aioson/docs/feature-expansion-taxonomy.md`.
 
 ### Installed skills (`.aioson/installed-skills/`)
 

package/template/.aioson/docs/LAYERS.md

@@ -56,8 +56,8 @@ See `docs/README.md` for format and naming conventions.
 ## Layer 4 — `.aioson/context/design-doc*.md`
 
 **What it is:** living decision document for the current feature or project scope.
-**Who writes it:** @discovery-design-doc.
-**Who updates it:** @dev at feature close, @discovery-design-doc when resuming.
+**Who writes it:** @orchestrator (maestro mode) on MEDIUM and @sheldon on the SMALL lean lane by default; @architect (merged mode) or @discovery-design-doc when those opt-in detours are in the sequence.
+**Who updates it:** @dev at feature close; the design-doc producer (@orchestrator maestro / @sheldon lean / @architect merged or @discovery-design-doc detour) when resuming.
 **When to use:** automatically — one per feature (`design-doc-{slug}.md`) or one project-wide (`design-doc.md`).
 **Cadence:** updated at the end of each feature implementation session. Decisions are append-only — never deleted.
 

package/template/.aioson/docs/agent-help.md

@@ -0,0 +1,126 @@
+---
+description: "Per-agent quick help printed by the --help activation token. Each section is keyed by `## @<agent>`; the agent prints ONLY its own section, translated to the interaction language, and stops."
+task_types: [help]
+triggers: [help, --help, agent options]
+---
+
+# Agent quick help (--help token)
+
+Consumed by the `## Help (--help)` section of each agent kernel: a standalone `--help` in the activation arguments makes the agent print its section below (localized) and stop — no work, no CLI calls, no questions. Keep every section short: what / when / options / typical calls / produces / next.
+
+## @product
+
+- **What:** product discovery — defines what to build, for whom, and why; writes the PRD base.
+- **When:** starting a new feature or project definition; the kickoff of every feature chain.
+- **Options:** `--auto` (run this feature on autopilot to `feature:close`), `--step` (drive each stage manually). Without a token and no standing choice, asks the run mode once at the PRD handoff.
+- **Typical:** `/product --auto build email notifications`, `/product redesign checkout`.
+- **Produces:** `prd-{slug}.md`, `features.md` row; seeds the autopilot scheme when armed.
+- **Next:** `@sheldon` (SMALL), `@orchestrator` (MEDIUM), `@dev` (MICRO), `@copywriter` (site).
+
+## @briefing
+
+- **What:** turns raw sketches from `plans/` into a structured, approved pre-production briefing.
+- **When:** an early idea needs framing and evaluation BEFORE committing to a PRD.
+- **Options:** none — point it at a `plans/` sketch or describe the idea.
+- **Typical:** `/briefing evaluate plans/loyalty-program.md`, `/briefing frame this idea: ...`.
+- **Produces:** `.aioson/briefings/{slug}/briefings.md` (+ prototype when the flow calls for it).
+- **Next:** `@briefing-refiner` (refine) or `@product` (PRD).
+
+## @briefing-refiner
+
+- **What:** iterative review of an existing briefing before PRD generation — the agent audits (findings), the CLI renders `review.html` (`aioson briefing:review`), you decide in the browser, structured feedback is applied back (`aioson briefing:apply-feedback`), and the loop repeats until nothing blocks the PRD.
+- **When:** a briefing exists but needs corrections, scope trims, or decisions; optionally a clickable prototype (and a reference-image visual identity) before @product.
+- **Options:** none — it locates the briefing by slug or asks which one.
+- **Typical:** `/briefing-refiner refine loyalty-program`.
+- **Produces:** review rounds (`review.html` + feedback JSON + report, archived per round) and the updated briefing (contract preserved); optionally `identity.md` + `prototype.html`.
+- **Next:** `@product` (after `aioson briefing:approve`), or prototype mode first for rich surfaces.
+
+## @dev
+
+- **What:** implements features per the spec/plan — code, migrations, interfaces, tests; drives all phases in one continuous run.
+- **When:** implementation entry point, resume after a break, or QA corrections.
+- **Options:** `--auto` (arm autopilot from here: implementation + review cycle run autonomously), `--step` (disarm autopilot for this feature — stop at the `@qa` handoff even in an always-autopilot project).
+- **Typical:** `/dev --auto`, `/dev` (follows the seeded scheme/flag), `/dev continue feature checkout`.
+- **Produces:** the implementation + tests, `spec-{slug}.md` updates, `dev-state.md` checkpoints.
+- **Next:** `@qa` (hub of the post-dev review cycle).
+
+## @deyvin
+
+- **What:** continuity-first pair programming — recovers recent context, works in small validated slices. Alias: `/pair`.
+- **When:** resuming known work, debugging together, a bounded fix on existing context.
+- **Options:** none. Hard boundary: new project/feature, broad redesign, or mixed product+UX+implementation scope → hands off immediately, never codes first.
+- **Typical:** `/deyvin continue yesterday's fix`, `/pair debug the failing upload test`.
+- **Produces:** the validated slice + session continuity records.
+- **Next:** the proper workflow agent when scope expands (`@product`/`@dev`).
+
+## @discover
+
+- **What:** reads key files/artifacts and builds the semantic knowledge cache in `.aioson/context/bootstrap/` (what the system is, does, how it works, current state).
+- **When:** session start on broad work, after big landings, or when agents warn `bootstrap < 4/4` / stale.
+- **Options:** none.
+- **Typical:** `/discover` (full refresh).
+- **Produces:** `bootstrap/how-it-works.md`, `bootstrap/current-state.md` (+ archive), instant context for every other agent.
+- **Next:** whatever agent you originally needed — discover is a preparation step.
+
+## @neo
+
+- **What:** the system router — shows the full picture (project state, workflow stage, pending work) and routes you to the right agent. Never implements, never produces artifacts.
+- **When:** you are lost, between features, or unsure which agent/lane fits the task.
+- **Options:** none.
+- **Typical:** `/neo where are we?`, `/neo what should I run next?`.
+- **Produces:** orientation + a concrete routing recommendation.
+- **Next:** the agent it names.
+
+## @orache
+
+- **What:** deep domain investigation before a squad/product push — real frameworks, anti-patterns, benchmarks, reference voices, vocabulary of the field.
+- **When:** entering an unfamiliar domain, or before `@squad` assembles specialists.
+- **Options:** none — give it the domain/question; it reuses the `researchs/` cache (7-day TTL).
+- **Typical:** `/orache investigate the B2B onboarding-tools market`.
+- **Produces:** a domain dossier + cached research under `researchs/`.
+- **Next:** `@squad`, `@product`, or `@briefing` depending on the goal.
+
+## @orchestrator
+
+- **What:** the MEDIUM spec maestro — fans out to analyst/architect/pm (+ux-ui) as sub-agents and consolidates one gated spec package (requirements, spec with Gates A/B/C, design-doc, readiness, plan, harness contract). MEDIUM only.
+- **When:** feature classified MEDIUM, right after `@product`.
+- **Options:** none at activation — under autopilot it seeds the scheme, completes its stage, and crosses into `@dev` automatically.
+- **Typical:** `/orchestrator continue feature billing-portal`.
+- **Produces:** the gated spec package + `dev-state.md` cold-start packet.
+- **Next:** `@dev`.
+
+## @tester
+
+- **What:** engineering-grade test suite for already-implemented apps — coverage gaps, edge cases, mutation-style checks. Tests what exists; never implements features.
+- **When:** `@qa` flags a coverage gap, or you want a systematic test pass on a finished surface.
+- **Options:** feature-scoped via the workflow (`--feature=<slug>` when invoked through the CLI prompt).
+- **Typical:** `/tester cover feature checkout`, or auto-invoked by `@qa` under autopilot.
+- **Produces:** the test suite + a coverage report; surfaces dev-owned blocking gaps.
+- **Next:** `@dev` (blocking gaps) or back to `@qa` (sign-off).
+
+## @pentester
+
+- **What:** structured adversarial security review — maps the threat surface and produces reproducible findings under an explicit scope contract (not a free-form hacker).
+- **When:** sensitive surface (auth, money, uploads, secrets, external URLs) — via `@qa`'s trigger or on demand.
+- **Options:** `--mode=app_target --feature=<slug> --scope=<target>` via `aioson agent:prompt pentester`.
+- **Typical:** `/pentester review the auth endpoints of feature accounts`.
+- **Produces:** `security-findings-{slug}.json` (owners + severities; `@qa` owns closure).
+- **Next:** `@dev` (open dev-owned findings) or back to `@qa`.
+
+## @qa
+
+- **What:** risk-first review — objective findings, the runtime smoke gate (build + migrate + boot + Core happy-path on the real stack), and the post-dev routing hub.
+- **When:** right after `@dev`; re-verification after corrections.
+- **Options:** none at activation — verdicts and routing are evidence-driven.
+- **Typical:** `/qa verify feature checkout`, or auto-invoked by `@dev` under autopilot.
+- **Produces:** QA report + verdict (PASS/FAIL), Gate D, corrections plans on FAIL.
+- **Next:** `@dev` (FAIL), `@tester`/`@pentester` (triggers), `@validator` (harness contract), or STOP recommending `aioson feature:close` (human gate).
+
+## @sheldon
+
+- **What:** the SMALL single spec authority (lean lane) — PRD gap analysis, sizing, enrichment, and the full collapsed spec package in one pass.
+- **When:** feature classified SMALL, right after `@product`; or PRD quality review on demand.
+- **Options:** none at activation — under autopilot it seeds the scheme, completes its stage (`--complete=sheldon`), and crosses into `@dev` automatically.
+- **Typical:** `/sheldon continue feature quick-filters`.
+- **Produces:** `sheldon-enrichment-{slug}.md`, `spec-{slug}.md` (Gates A/B/C), design-doc, readiness, plan, harness contract, `dev-state.md`.
+- **Next:** `@dev`.

package/template/.aioson/docs/autopilot-handoff.md

@@ -1,31 +1,41 @@
 ---
-description: "Autopilot handoff protocol: automatic agent chaining across the feature workflow — the analyst→dev pre-dev chain and the post-dev review cycle (dev→qa→tester/pentester→validator) — with deterministic routing and explicit stop conditions. The chain never auto-runs feature:close/publish."
+description: "Autopilot handoff protocol: automatic agent chaining across the feature workflow — the opt-in pre-dev detour chain and the post-dev review cycle (dev→qa→tester/pentester→validator) — with deterministic routing and explicit stop conditions. The chain never auto-runs feature:close/publish."
 task_types: [handoff, autopilot]
 triggers: [auto handoff, autopilot, next agent]
 ---
 
-# Autopilot handoff (analyst → dev → review cycle)
+# Autopilot handoff (feature start → dev → review cycle)
 
-Opt-in protocol that removes manual handoff confirmations in the deterministic segments of the feature workflow. Two segments:
+Opt-in protocol that removes the **mechanical** handoff confirmations across the whole feature workflow — the "type /sheldon", "type /dev", "run phase 2", "run qa" stops. Genuine human decisions (product scope, sizing/enrichment) still happen interactively inside their agents; autopilot only removes the mechanical "run the next thing" step once an agent's own work is settled. Two segments:
 
-1. **Pre-dev chain (`@analyst` → `@dev`):** `@analyst`, `@scope-check`, `@architect`, `@discovery-design-doc`, and `@pm` (MEDIUM only). Upstream agents (`@briefing`, `@product`, `@sheldon`) always stay manual — they end on genuine human decisions.
-2. **Post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` → `@validator`):** once a human starts `@dev`, the implementation and review agents chain automatically until the feature is ready to close. `@qa` is the hub: it owns the routing to the specialized agents and the corrections loop.
+1. **Spec → dev chain (`@product → @sheldon`/`@orchestrator` → `@dev`):** when autopilot is on, each spec agent — once its own decisions are resolved (no open `AskUserQuestion`, the gates it owns approved) — seeds the agentic scheme and auto-invokes the next stage instead of stopping. It crosses the pre-dev boundary via the `dev-state.md` cold-start packet, not by carrying raw upstream chat forward. `@analyst`, `@architect`, `@pm`, `@scope-check`, and `@discovery-design-doc` chain automatically only when an opt-in detour adds them to the active sequence.
+2. **Post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` → `@validator`):** the implementation and review agents chain automatically until the feature is ready to close. `@qa` is the hub: it owns the routing to the specialized agents and the corrections loop.
+
+Both segments stop only at the human close/publish gate (`feature:close`) and at the hard stop conditions below. Historically Segment 1 stayed manual (upstream agents end on human decisions); autopilot now crosses it too, but only mechanically — a real product/sizing decision still pauses for the human before any auto-invoke.
 
 ## Activation
 
-Autopilot is active only when ALL are true:
+Autopilot is active when BOTH of the first two hold, gated by the third:
+
+1. Either `project.context.md` frontmatter has `auto_handoff: true`, OR `.aioson/context/workflow-execute.json` exists with `agentic_policy.enabled: true` **and `feature` matching the current slug** (the seeded scheme — a scheme left by a different/closed feature does NOT count, for any agent in the chain). **Per-feature disarm wins over the flag:** a scheme for the current slug with `agentic_policy.enabled: false` (written by `aioson workflow:execute . --feature={slug} --seed --step`) turns autopilot OFF for that feature even when `auto_handoff: true` — an explicit per-feature choice always beats the project default.
+
+**Inline run-mode tokens (highest precedence, human entry points only):** a standalone `--auto` or `--step` in the activation arguments of `@product` (kickoff) or `@dev` (late entry/override) IS the run-mode decision — the agent strips it from the task text and never asks. `--auto` seeds the scheme (arming the whole chain from that point); `--step` writes the disarmed scheme. Downstream agents (`@qa`/`@tester`/`@pentester`/`@validator`) do not parse tokens — they read the flag/scheme. Absent both, the run mode is not yet chosen: **`@product` asks it on screen at feature kickoff** (Autopilot / Step by step / Always autopilot — see product.md "Run mode"). Picking Autopilot seeds the scheme (activating this segment); "Always autopilot" also writes `auto_handoff: true`; Step by step leaves both unset = manual handoffs. Only `@product` asks — downstream agents read the flag/scheme and never re-prompt.
+2. A feature workflow is active (feature slug known).
+3. The current agent's own gate/verdict passed AND no genuine human decision is open (see stop conditions).
 
-1. `project.context.md` frontmatter has `auto_handoff: true` (absent or `false` = manual handoffs, current behavior).
-2. A feature workflow is active (feature slug known, classification SMALL or MEDIUM).
-3. The current agent's own gate/verdict passed (see stop conditions).
+## Seeding the agentic scheme
 
-Preferred runtime entrypoint:
+The first spec agent to finish under autopilot seeds the run's contract — this is the "scheme" the whole chain follows, and it is what makes a feature built the normal way (`@product → @sheldon`/`@orchestrator` → …) run to `feature:close` without the user launching anything:
 
 ```bash
-aioson workflow:execute . --feature={slug} --tool=<tool> --agentic
+aioson workflow:execute . --feature={slug} --seed --tool=<tool>
 ```
 
-`workflow:execute --agentic` is the central orchestration contract. It writes `.aioson/context/workflow-execute.json` with `agentic_policy`, including the review-loop caps, sidecar/scout policy, lane guard, current checkpoint, and resumable command. Prompt-level `Skill(aioson:agent:<next>)` chaining remains a compatibility fallback for clients that cannot let the gateway consume this checkpoint.
+`--seed` writes `.aioson/context/workflow-execute.json` (with `agentic_policy.enabled: true` — review-loop caps, `feature_close: human_gate`, and the stop conditions) plus `.aioson/context/workflow.state.json`. It is **seed-only**: it records the policy the interactive agents follow but does NOT drive stage transitions itself (the agents do, via `Skill(aioson:agent:<next>)` + `aioson workflow:next . --complete=<agent>`). Re-seeding the same slug is idempotent, and a stale `workflow.state.json` left by a feature that is no longer active in `features.md` is discarded and reseeded. Once the scheme exists with `agentic_policy.enabled`, autopilot is on for the whole feature even if `auto_handoff` was never written to frontmatter.
+
+**Seed failure is a stop condition.** The seeding agent must check the command result: a `different_active_feature` failure means another feature is genuinely active in `workflow.state.json` — surface it to the user (close/pause it, or `aioson feature:sweep .`) and stop with the manual handoff. Never continue the chain as if autopilot were armed when the seed failed.
+
+The headless/tracked runner `aioson workflow:execute . --feature={slug} --tool=<tool> --agentic` (without `--seed`) is the same contract but also advances checkpoints from the CLI — use it for non-interactive runs. Prompt-level `Skill(...)` chaining is how interactive Claude Code / codex sessions consume the scheme.
 
 ## Routing — deterministic, never LLM-chosen
 
@@ -45,13 +55,13 @@ When autopilot is active and no stop condition applies:
 3. If no runtime gateway is available, emit a one-line transition notice: `Autopilot: @<current> done → invoking @<next> (Ctrl+C to interrupt)`.
 4. Invoke `Skill(aioson:agent:<next>)` with the task `"continue feature {slug} — autopilot handoff from @<current>"`. No user prompt — Ctrl+C interrupts.
 
-## Segment 1 — pre-dev chain (`@analyst` → `@dev`)
+## Segment 1 — spec → dev chain
 
-SMALL feature: `@analyst` → `@scope-check` → `@architect` → `@discovery-design-doc` → `@dev`.
+SMALL feature (lean default): `@product` → `@sheldon` → `@dev`. Under autopilot: `@product`, once the PRD is settled, seeds the scheme and invokes `@sheldon`; `@sheldon`, once sizing/enrichment is confirmed and its lean-lane artifacts + `dev-state.md` are written, completes its own stage (`aioson workflow:next . --complete=sheldon`) and invokes `@dev`. The full-merged SMALL detour auto-chains `@analyst` → `@architect` → `@dev` when opted in (with `@scope-check`/`@discovery-design-doc` only if the sequence adds them).
 
-MEDIUM feature: `@analyst` → `@architect` → `@discovery-design-doc` → `@pm` → `@scope-check` → `@dev`.
+MEDIUM feature (maestro default): `@product` → `@orchestrator` → `@dev`. Under autopilot: `@product` seeds + invokes `@orchestrator`; `@orchestrator`, once its gated spec package (Gates A/B/C approved, readiness ready) + `dev-state.md` are written, invokes `@dev`. The maestro fans out to `@analyst`/`@architect`/`@pm` as sub-agents, not as workflow stages; those chain as stages only under an opt-in full-chain detour.
 
-The prompt-only fallback still stops before the FIRST `@dev` activation because `@dev` is a heavy phase and needs a compact operational handoff. Runtime agentic mode may cross this boundary only by starting a checkpointed `@dev` activation from the context package, not by carrying raw upstream chat forward. If the gateway cannot start that activation, stop with the normal `/compact` + `/dev` recommendation for same-feature continuation. Recommend `/clear` only when the user needs a hard reset, a feature switch, polluted context, or a security-sensitive reset.
+Crossing into `@dev` goes through the `dev-state.md` cold-start packet the spec agent writes — `@dev`'s session-start protocol loads only that minimal package, so `@dev` does not inherit the heavy upstream chat; transparent auto-compact trims the rest. That is why the crossing is safe without a manual `/compact`. The spec agent still stops with the normal manual `/dev` recommendation if it has an open product/scope/sizing decision or a gate it owns is not approved. Recommend `/clear` only when the user needs a hard reset, a feature switch, polluted context, or a security-sensitive reset.
 
 ## Segment 2 — post-dev review cycle (hub = `@qa`)
 
@@ -84,15 +94,15 @@ Routing table (each row is followed only when autopilot is active and no stop co
 ## Stop conditions — break the chain and emit the normal manual handoff
 
 1. **`feature:close` / publish** — ALWAYS the human gate. When `@qa` (PASS, nothing pending) or `@validator` (PASS) is the last clean step, STOP and recommend `aioson feature:close . --feature={slug}`. Never auto-run `feature:close`, `feature:archive`, `npm publish`, or any publish/close action.
-2. **First `@dev` entry without runtime gateway** — prompt-only clients stop here (Segment 1). Runtime agentic mode may continue only through a fresh checkpointed `@dev` activation.
+2. **Genuine human decision open** — a spec agent with an unresolved product/scope/sizing question (an open `AskUserQuestion`, or a gate it owns not yet approved) finishes that decision with the human before any auto-invoke, and stops with the normal manual handoff. Autopilot removes mechanical stops, never real decisions. (This replaces the old "always stop before the first `@dev`" rule: the crossing is now automatic once the spec agent's own decisions are settled and `dev-state.md` is written.)
 3. **Corrections cap reached** — review cycles are bounded by `agentic_policy.review_cycle` (default 3); when `review-cycle:advance` returns `stop_cycle_limit`, stop and escalate to the human.
 4. **Critical security finding** — the `@qa` corrections security gate (auth/secret/credential/session/password/token/PII/encryption keywords) blocks the auto-loop; stop and require human intervention.
-5. **Verdict not clean / gate or readiness blocked** — `@scope-check` not `approved`/`patched`, `@architect` Gate B blocked, `@discovery-design-doc` readiness `blocked`, `@pm` Gate C blocked, `@validator` FAIL with no safe corrections path: stop and route to the owner manually.
-6. **Context budget** — estimated usage ≥ `context_warning_threshold` (`.aioson/config.md`): write the compaction checkpoint to `.aioson/context/last-handoff.json`, stop, and recommend `/compact` for same-feature continuation. The workflow resumes from `.aioson/context/workflow.state.json` — the next session re-enters autopilot automatically. Recommend `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+5. **Verdict not clean / gate or readiness blocked** — the `@orchestrator` maestro spec package not gate-approved (Gates A/B/C) or its readiness `blocked`, `@validator` FAIL with no safe corrections path (and, when present as detours, `@architect` Gate B / merged-mode readiness `blocked`, `@pm` Gate C blocked, `@scope-check` not `approved`/`patched`, or `@discovery-design-doc` readiness `blocked`): stop and route to the owner manually.
+6. **Context budget** — estimated usage ≥ `context_warning_threshold` (`.aioson/config.md`): write the compaction checkpoint to `.aioson/context/last-handoff.json`, stop, and recommend `/compact` for same-feature continuation. The workflow resumes from `.aioson/context/workflow.state.json` — the next session re-enters autopilot automatically. Recommend `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
 7. **Ambiguity** — workflow state unavailable AND routing ambiguous, or any real decision requires user input: stop and ask, manually.
 
 The user can interrupt at any time (Ctrl+C); autopilot never retries an interrupted invocation.
 
 ## Rationale
 
-Industry-validated design (see `researchs/auto-handoff-pipeline-2026/summary.md`): deterministic routing beats LLM routing; human gates belong where they catch mistakes — at the start of implementation (`@dev` entry: compact operational handoff) and at the irreversible boundary (`feature:close`/publish). Every autonomous loop needs explicit exit conditions and bounds (the corrections cap, the re-entry guard); per-hop context checkpointing is the load-bearing cost mitigation.
+Industry-validated design (see `researchs/auto-handoff-pipeline-2026/summary.md`): deterministic routing beats LLM routing; human gates belong where they catch mistakes — at the start of implementation (`@dev` entry: compact operational handoff) and at the irreversible boundary (`feature:close`/publish). Every autonomous loop needs explicit exit conditions and bounds (the corrections cap, the re-entry guard); per-hop context checkpointing is the load-bearing cost mitigation.

package/template/.aioson/docs/dev/execution-discipline.md

@@ -83,6 +83,47 @@ Before marking any task or feature done:
 3. confirm exit code `0`
 4. only then mark done
 
+### Exit-code honesty (never auto-deceive)
+
+A gate's verdict is its exit code, not your impression of it:
+
+- **Exit 127 = command not found.** That is a FAILURE, not a pass — a missing
+  tool/dependency. Stop and report; never read "no error output" as "no errors".
+- **Exit 0 with empty output** on a command that should produce output (a
+  typecheck over N files, a test run) means the command did **not** run. Verify
+  it actually executed (e.g. the output file exists and is non-empty) before
+  trusting it.
+- **Exit 124 = timeout.** The command hung — investigate, do not blind-retry.
+- When you cite a gate as evidence ("typecheck clean", "smoke passed"), paste the
+  exact command, the exit code, and the last lines of output. "exit 0" without
+  the command is not evidence.
+
+### Static gate (`SG-*`) — proof per acceptance criterion
+
+`aioson harness:check . --slug={slug}` also evaluates the contract's build-free
+**`SG-*`** static criteria (`must_match` / `must_not_match` + parse-check) on
+every run — they gate `@dev`-done even before the app builds. When you self-review
+an AC backed by an `SG-*` criterion, the evidence **is** the pattern hit: cite the
+`file:line` where `must_match` matched. A failing `SG-*` (a missing pattern, a
+forbidden `TODO`/`as any`, a truncated file) blocks done exactly like a failing
+test — fix the code, never relax the pattern.
+
+### Runtime sub-gate (runtime features — has_api / DB / prototype)
+
+A passing unit suite is not "done" for a feature that ships a backend, a database, or a clickable prototype.
+Unit tests mock the DB/auth/network; they prove the parts in isolation, not the whole running app. Before
+declaring such a feature done, you must have **run the real stack at least once**:
+
+1. **build** the app (`pnpm build` / `npm run build` / `tsc -p .`) — the whole thing, not a subset
+2. **apply** the migrations to a real/ephemeral DB (`prisma migrate reset --force` / `migrate deploy`) — a
+   `.sql` file on disk is not an applied migration
+3. **boot** server + client; confirm a health probe (`/api/health`) returns 200
+4. **drive** the prototype's Core happy-path (create/list/switch/edit/archive of the primary objects) end to
+   end on the running stack
+
+If no smoke/boot harness exists, building one is part of the slice — do not substitute a unit test. This is
+the same evidence `@qa`'s Runtime smoke gate and the §2c `RG-*` contract criteria require.
+
 Update `skeleton-system.md` whenever files are created, deleted, or materially changed.
 
 ## `*update-skeleton`

package/template/.aioson/docs/dev/phase-loop.md

@@ -0,0 +1,50 @@
+---
+description: "Dev phase loop — auto-continue across phases, per-phase verification sub-agents, and compaction between phases."
+agents: [dev, deyvin]
+task_types: [implementation, verification]
+triggers: [phase loop, auto-continue phases, per-phase verification, compact between phases]
+---
+
+# Dev phase loop — auto-continue, per-phase verification, compaction
+
+On-demand detail for @dev's `## Phase loop` kernel section. Applies when a phased plan drives the work (`implementation-plan-{slug}.md` or a Sheldon `.aioson/plans/{slug}/manifest.md`).
+
+## The loop
+
+**Auto-continue is the default and it is imperative — a phased plan runs to the END OF THE FEATURE in one continuous drive, not one phase per turn** (`phase_loop.auto_continue` in `.aioson/config/verification.json`). After a phase's gate is clean you will feel the pull to stop and report "Phase N done — continue?"; that pull is the exact bug this loop exists to defeat. Do NOT stop, do NOT ask, do NOT summarize-and-end between phases — proceed straight into the next phase. The per-phase verification report is the checkpoint that replaces the human "continue?": a clean report advances automatically; a failing one (after in-phase fix retries) is the only thing that halts the loop mid-feature. The run otherwise halts only at the end-of-feature gate or at a genuine hard stop (real ambiguity, a blocked gate, or a context ceiling on a host without transparent auto-compact). Set `auto_continue: false` only if you deliberately want to pause for confirmation between phases.
+
+After finishing each phase:
+
+1. **Close the phase.** Mark it `done` in the manifest (`pending → in_progress → done`, never skip ahead) and update `spec-{slug}.md` checkpoints.
+2. **Per-phase gate.** If `.aioson/plans/{slug}/harness-contract.json` exists, run `aioson harness:check . --slug={slug}` (add `--strict` for MEDIUM / harness-driven work) — this also evaluates the build-free `SG-*` static criteria, so a stubbed/placeholder slice fails here before the build even runs. Then run `aioson audit:code . --changed --json` for a fast, build-free code-quality scan of this phase's diff (anti-patterns / TODOs / dead code / duplication): a HIGH finding is fix-before-advancing, MED/LOW advisory.
+3. **Per-phase verification.** Run:
+   ```bash
+   aioson verification:plan . --feature={slug} --trigger=per-phase --json
+   ```
+   For every agent with `run: true`, dispatch it as a sub-agent on the plan's top-level `host` plus that agent's `mode` / `model`, scoped to this phase's changed files:
+   - `mode: native` → an in-harness sub-agent. On Claude Code use the Task tool with that `model` tier (e.g. `sonnet-4.6`); on codex/opencode use their own configured model. The sub-agent writes its `report` file (e.g. `qa-report-{slug}.md`) and returns it to @dev.
+   - `mode: external` → only the explicitly configured cross-vendor auditor (`cross_check`); never spawn one otherwise.
+   Read the report: **PASS** → continue. **Bugs** → fix them within this phase, re-run `harness:check`, and re-dispatch — up to `phase_loop.max_fix_retries_per_phase` times, then stop and surface the failure instead of advancing.
+4. **Checkpoint, then keep going — do NOT end the turn.** Write the cold-start packet as a crash/interrupt safety net:
+   ```bash
+   aioson dev:state:write   # slug, completed phase, next phase, manifest path, required context, decisions
+   ```
+   Then continue **immediately** into the next phase in the SAME turn. Context management is the host's job, never a reason to stop:
+   - **Claude Code (and any host with transparent auto-compact):** never self-issue `/compact` and never end your turn between phases. Auto-compact shrinks context in place when it fills — you just keep implementing. With `compact_between_phases: true`, "compact" means *write the checkpoint above*, NOT *stop for a manual compaction*.
+   - **codex / opencode (no transparent auto-compact):** the host wrapper re-enters on a fresh context and reloads via `aioson dev:resume-data .`. Only these hosts break the turn, and only their wrapper — never a bare prompt — restarts the loop.
+   The checkpoint exists so an interrupted run resumes cheaply, not so you pause. A phase boundary with a clean gate is a checkpoint, never a stopping point.
+5. **End-of-feature gate (after the last phase only).** Hand off to `@qa`, which runs the full runtime smoke (build + migrate + boot + Core happy-path) plus `@tester`/`@pentester`/`@validator` per:
+   ```bash
+   aioson verification:plan . --feature={slug} --trigger=end-of-feature
+   ```
+
+## Token economy
+
+- The per-phase check is **light**: one cheap-tier sub-agent, changed-files scope, capped by `budget.max_subagents_per_phase`.
+- It is **suppressed on MICRO** (`budget.skip_on_micro`) — MICRO phases just auto-continue with no sub-agent.
+- The **expensive full runtime smoke runs once**, at end-of-feature only (`budget.full_smoke = end-of-feature-only`) — never per phase.
+- Context stays small without stopping: on Claude Code transparent auto-compact shrinks it in place as it fills, and the between-phase `dev:state:write` checkpoint lets any compaction (auto or a host-driven fresh context) resume the next phase cheaply. You get the small-context savings without ever ending the turn.
+
+## Configuration
+
+All knobs live in `.aioson/config/verification.json` (see `.aioson/docs/verification-config.md`): per-agent `enabled` / `triggers` / `dispatch` (per host), `cross_check`, `budget`, and `phase_loop` (`auto_continue`, `compact_between_phases`, `max_fix_retries_per_phase`).