@jaimevalasek/aioson 1.33.1 → 1.37.0

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.37.0] - 2026-07-06
+
+**Full-feature autopilot + CLI-owned briefing refinement.** Two independent arcs land together. A feature built the normal way (`@product` → `@sheldon`/`@orchestrator` → `@dev`) can now run unattended through `@qa`/`@tester`/`@pentester`/`@validator` to `feature:close` — stopping only at genuine human decisions; `@product` asks the run mode once at kickoff (no hidden flag), settable inline (`--auto`/`--step`) or disarmed per feature. Separately, `@briefing-refiner`'s review surface stops being hand-written every round: the CLI now owns the schema, the render, and the apply, closing an explicit iterate-until-clean loop.
+
+### Added
+- **Full-feature autopilot.** `workflow:execute --seed` seeds the agentic scheme without advancing (idempotent, feature-scoped); `@product`/`@sheldon`/`@orchestrator` seed it and cross the pre-`@dev` gate via the `dev-state.md` cold-start packet; `@dev`/`@qa` honor it through the post-dev review cycle. `@product` asks the run mode on screen at kickoff (Autopilot / Step by step / Always autopilot) — never silent-manual by default. (`e24bfa5`, `9afc993`)
+- **Inline run-mode tokens** `--auto`/`--step` — `/product --auto <task>` / `/product --step <task>` answer the kickoff question inline (highest precedence); `/dev --auto` / `/dev --step` arm or disarm autopilot mid-chain for the current feature. Disarm is record-only (`workflow:execute --seed --step`) and beats a project-wide `auto_handoff: true` for that feature. (`70e826b`)
+- **`--help` activation token** on the 13 most-used agents — localized quick help (what/when/options/artifacts/next agents), zero kernel-byte cost beyond a 3-line trigger to the shared `agent-help.md`. (`bafaa2a`)
+- **`aioson briefing:review`** — parses `briefings.md`, strictly validates the agent's audit findings (`refinement-findings.json`: category/severity/blocking/recommendation per section), and renders the localized `review.html` + canonical `refinement-feedback.json` (schema **v1.1**: `findings[]` + `round`) + `refinement-report.md`. Refuses to clobber user-exported pending feedback (`--force` to override); the round counter survives applies via the per-round archives. (`43661a7`)
+- **`aioson briefing:apply-feedback`** — dry-run validation + summary without `--confirm` (the agent presents it and asks), real apply with it: structured-JSON-only edits, mandatory sections preserved, `approved` → `draft` revert, consumed feedback/findings archived as `*.applied-round{N}.json`. A **pending blocking finding** forces `resolve_blockers` even when `blocking_items` is empty. `--declined` records skipped changes without touching the briefing. (`43661a7`)
+- **`review.html` v2** — audit findings rendered per section with their own decision (`pending`/`accepted`/`rejected`/`deferred`) and working category filters; **localStorage autosave + draft restore** (closing the tab loses nothing); File System Access saves with a persistent handle and **degrades to download on SecurityError** (the sandboxed-preview bug); a **copy-path** affordance next to the save target and a stable save-picker id so the OS dialog reopens in the briefing folder on later rounds; en/pt localized surface. (`43661a7` + polish)
+- **`verify:artifact --kind=review`** + `briefing-refiner` in `AGENT_ARTIFACT_KIND` — the done-gate auto-fires at `agent:done --slug=...` and rejects hand-rolled surfaces (missing marker / fallbacks / external resources / invalid feedback JSON); staleness after an apply is advisory. (`43661a7`)
+
+### Fixed
+- **`@dev` phase-loop no longer self-stops.** The loop told `@dev` to `/compact` between phases — on Claude Code that ends the turn, so a feature ran one phase and waited instead of driving to the end. `@dev` never self-issues `/compact` now; `verification:plan` emits a deterministic `continuation_directive` instead. (`3a0fd34`)
+- **Autopilot chain-integrity audit** — four bugs behind the same reported symptom ("dev finished → manual /qa handoff"): a lean-lane `@sheldon` stage could re-activate backwards after `@dev` completed; tracked sessions didn't consult the seeded scheme as an autopilot signal; `--seed` hard-failed on a stale abandoned-feature guard instead of reseeding; downstream triggers didn't check the seeded scheme's feature slug against the current one. (`a0010cd`)
+- **Boolean-only argv flags** — `--seed` / `--seed-only` / `--confirm` / `--declined` / `--allow-stale` / `--step` could each swallow the path positional (e.g. `--declined .` silently defaulted to cwd). (`8a9999a`, `abc1058`, `70e826b`)
+- **`feature:close` retires per-feature runtime pointers** (`dev-state.md`, `workflow.state.json`, `workflow-execute.json`) when they reference the closed slug, so a future `@dev` cold-start can't "resume" a done feature and the next feature's `--seed` doesn't collide. (`bd34451`)
+- **Declined feedback no longer dead-ends the loop** — `briefing:apply-feedback --declined` archives the consumed feedback (`refinement-feedback.declined-round{N}.json`, findings kept since the briefing did not change) so the next `briefing:review` regenerates without `--force`, the declined round still counts toward the round counter, and declining stale feedback is allowed (decline writes nothing, so the source-hash guard does not apply). `kind=review` external-resource check hardened against false positives from briefing text quoting HTML/CSS. (`abc1058`)
+- **Windows executable resolver** never tests the extensionless candidate on `win32` — npm's extensionless shim is a shell script that `ENOENT`s on spawn despite existing (hit via `codex`/`opencode`); malformed `PATHEXT` empty segments are filtered, and a spawn failure between `spawn()` and the child-wait now fails cleanly instead of surfacing as an unhandled error (or a false exit code 0). (`25dcb60`)
+
+### Changed
+- **`@briefing-refiner`** rewritten around the CLI: explicit refinement-loop contract (generate → collect → dry-run + confirm apply → regenerate while blockers or material text changes remain → exit to `briefing:approve`/`@product` or prototype mode); handoff names the three feedback-return routes (direct save / download+replace / **paste JSON in the chat**) and instructs opening `review.html` in a real browser — editor previews are sandboxed; a non-blocking finding nudges the reference-image identity route for rich surfaces with no `identity.md`; the V1 "no dedicated refinement CLI" constraint is retired. Answers left in finding/section `note` fields are folded into `current_text` by the agent before the CLI writes — notes alone never reach the briefing. (`ad22cda`, `abc1058`)
+- **`identity.md` reaches every consumer of the `interface-design` engine** — the engine's SKILL now resolves it first (briefing scope → project brand → intent-first) so any consumer inherits the step; `@dev` reads it as a feature-mode UI input next to the prototype reference (a lean-lane feature without prototype/ux-ui no longer ships generic visuals over an existing brand); `@ux-ui`'s blank-`design_skill` stop offers the reference-image route alongside presets, mirroring `@setup`. (`35891f9`)
+- **Docs sweep** — `autopilot-handoff.md` rewritten to the current model (tokens, precedence, seeding, stop conditions) with an English counterpart; 14 PT/EN pages updated to the CLI-owned refinement loop and identity routes; agent-count headers and cycle-cap references corrected. (`95b99d5`, `90c77d1`, `16f9172`, `4c6507e`)
+
+Suite green (3587 pass / 0 fail / 1 skip).
+
+## [1.36.0] - 2026-06-30
+
+**Reference-image-driven visual identity.** A project's UI no longer has to inherit a fixed design preset's identical look (the generic, "made-by-AI" sameness). The user provides reference images — a brand/identity set and an optional component/structure set — which are extracted **once** into a text `identity.md` that the `interface-design` engine applies. The build reads the text, never the images, so it ports to a vision-less harness, is user-editable, and is gateable. Purely **additive** — the fixed presets stay as raw material for `@design-hybrid-forge` / `@site-forge`; the new path is the recommended default alongside them.
+
+### Added
+- **`reference-identity-extract` process skill.** One vision pass reads the identity + structure images and emits `identity.md` (palette / type / spacing / depth / motion / signature moves + per-component structure notes); the image-less fallback defers to `interface-design`'s intent-first Phase 0. Lives under `skills/process/` (always installed), not `skills/design/` (profile-gated at install). (`d0e21c3`)
+- **`verify:artifact --kind=identity`** — a build-free gate (resolved via `--file`) proving the token skeleton, both anti-sameness anchors (pillars + signature moves), and the component-structure section are present, with no placeholder / unfilled hex. `availableKinds()` self-registers it; two new paths appended to `MANAGED_FILES` for `aioson update` backup-safety (no preset enumeration touched). (`d0e21c3`)
+- **`docs/reference-identity.md`** documents the flow, the two scopes (per-briefing `.aioson/briefings/{slug}/identity.md` and project brand `.aioson/context/identity.md`), the gate, and the no-vision / cross-harness fallback. (`d0e21c3`)
+
+### Changed
+- **`@briefing-refiner` prototype mode** gains the reference-image intake: the user drops images into `references/{identity,structure}/`, the agent extracts `identity.md` and self-gates; no images → `interface-design` runs intent-first (never blocks). **`@setup` Step 5** offers "interface-design + reference images" as the recommended visual route (still explicit-confirm, no auto-select). (`d0e21c3`)
+- **`@ux-ui` Step 0** frames `identity.md` as the INPUT that parameterizes the single `interface-design` engine — not a second skill, so ONE SKILL ONLY is preserved. `prototype-forge` consumes it as the engine overlay; `interface-design`'s continuity note reuses it as the extracted-from-references form of `system.md`. (`d0e21c3`)
+
+Suite green (3549 pass / 0 fail); +14 tests (5 `identity` ruleset, 9 wiring/parity).
+
+## [1.35.0] - 2026-06-28
+
+The **lean-harness redesign**: fewer default agent hops, with quality held by deterministic gates and configurable verification sub-agents rather than by agent count. SMALL and MEDIUM now each route through a single spec authority; `@analyst` / `@architect` / `@pm` / `@discovery-design-doc` / `@scope-check` / `@ux-ui` become opt-in detours (none deleted).
+
+### Changed
+- **SMALL is the lean lane by default.** The default SMALL chain is now `@product → @sheldon → @dev → @qa` (was `@product → @analyst → @scope-check → @architect → @discovery-design-doc → @dev → @qa`), with `@sheldon` as the single spec authority. Supersedes 1.34.0's *opt-in* lean lane. Updated in both routing sources (`workflow-next.js` + `workflow-plan.js`). (`aea0894`)
+- **MEDIUM is the `@orchestrator` maestro.** The default MEDIUM chain is now `@product → @orchestrator → @dev → @pentester → @qa` (project: `@setup → @product → @orchestrator → @dev → @qa`). `@orchestrator` is repurposed from a paper-protocol parallel-lane coordinator into the MEDIUM single spec authority — it **fans out** to `@analyst` / `@architect` / `@pm` (+ `@ux-ui` when UI-heavy) sub-agents, then consolidates / verifies / redoes their output into one gated spec package (requirements + spec [Gates A/B/C approved] + design-doc + readiness + implementation-plan + harness-contract) and hands to `@dev` — the horizontal counterpart to `@sheldon`'s vertical lean lane. (`d03e1ec`)
+- **Spec hops demoted to opt-in detours** (none deleted): `@discovery-design-doc`, `@scope-check`, `@ux-ui` (3b) and `@analyst`, `@architect`, `@pm` (4a). `@architect` runs in **merged mode** by default (also producing design-doc + readiness + dev-state) when the active sequence omits `@discovery-design-doc`; `@scope-check`'s deterministic drift check (`spec:analyze`) is now enforced at the `@dev` / `@qa` done gate (`finalizeCurrentStage`), blocking on real drift (readiness-blocked / invalid harness contract) without false-blocking artifact-light features. (`6db76f9`)
+
+### Added
+- **Per-agent, per-host verification config.** `.aioson/config/verification.json` (auto-generated, hand-editable) declares which verification sub-agents (`qa` / `tester` / `pentester` / `validator`) run, when (`per-phase` / `end-of-feature` / `sensitive-surface`), and on which model — keyed by host harness with `native` (in-harness sub-agent on a Claude tier or the host's own model) vs `external` (cross-vendor auditor) dispatch, plus a token budget. `src/verification-policy.js` is the reader; degrades to safe defaults on a missing/malformed file. (`dc4bd42`)
+- **`aioson verification:plan` + `@dev` phase loop.** The new deterministic command resolves, for a slug + trigger + host, which verifiers run and on which model. `@dev` now runs a phased plan as a loop that **auto-continues by default** (no human "continue?" between phases), compacts between phases (`dev:state:write` → `/compact` or fresh context → `dev:resume-data`), and runs the per-phase verification whose report replaces the human checkpoint. Per-phase checks are light and suppressed on MICRO; the full runtime smoke runs once at end-of-feature. Full protocol in `.aioson/docs/dev/phase-loop.md`. (`4c6ac66`)
+- **Single-spec-authority handoff gate + `@sheldon` PRD-enrichment step.** `handoff-contract.js` now enforces the collapsed done-gate (Gates A/B/C + approved implementation-plan + contract integrity) for **both** the lean `@sheldon` lane and the maestro `@orchestrator` lane; the orchestrator's expected artifacts become the gated spec package in maestro mode. The MEDIUM maestro can optionally harden the PRD via `@sheldon`'s enrichment first (opt-in pre-step or a fan-out stream — never a mandatory hop). (`d03e1ec`, `da0c1dd`)
+
+### Docs
+- Swept the framework documentation to the new default chains — `CLAUDE.md`, `config.md`, `autopilot-handoff.md`, `workflow-lean-lane.md` (premise flipped: lean is the SMALL default, "full-merged" is the opt-in heavier chain), the `aioson-spec-driven` skill + references, `prd-contract.md`, `LAYERS.md`, and `pm.md`. (`75104d5`, `8e7b0e1`)
+
+## [1.34.0] - 2026-06-27
+
+### Added
+- **Mandatory runtime smoke gate.** A feature with a backend, a database, or a clickable prototype no longer closes on green unit tests + `tsc` alone. The §2c `RG-build` / `RG-migrate` / `RG-boot` / `RG-smoke` criteria must run on the real stack. `@qa`'s Runtime smoke gate, `@validator`'s Step-0 precheck, and the `harness-contract` schema enforce it.
+- **Deterministic contract-integrity gate.** New `src/harness/contract-integrity.js` + `contract-integrity-gate.js` flag a runtime feature whose contract is missing / has no `RG-*` / pads binary criteria with duplicate verification commands. It is wired as a real gate into `workflow:next --complete=dev|qa` and `feature:close --verdict=PASS` (hard-blocks, independent of `ready_for_done_gate`), and as a non-blocking advisory `contract:integrity` step in `agent:epilogue` for untracked sessions. Runtime detection uses prototype-manifest, migration/Prisma paths in `progress.*`, and the git working tree; the same detection backs standalone `aioson harness:check`.
+- **Opt-in lean lane + full-merged preset.** Drop `.aioson/docs/presets/workflow.config.lean.json` into `.aioson/context/workflow.config.json` to route `@product → @sheldon → @dev → @qa`, with `@sheldon` as single spec authority (RF-LEAN) producing requirements/spec/design-doc/readiness/implementation-plan/harness-contract in one pass. The `full-merged` preset instead folds `@discovery-design-doc` into `@architect`. Built-in `src/` routing defaults are unchanged (full chain stays the default).
+- **Deterministic lean detection for `@sheldon`.** `agent:prompt sheldon` reads `workflow.config.json` and injects the RF-LEAN directive when the lean lane is active, so a directly-activated `@sheldon` no longer falls back to enrichment mode and hands to `@analyst`.
+- **`aioson review:feature`.** One-shot review pass for an already-implemented feature: resolves the slug, runs the deterministic `security:audit`, and prepares the `@pentester` + `@tester` activation prompts (`--scope`, `--skip-audit`, `--out-dir`, `--json`). `agent:prompt tester --feature=<slug>` now pins the slug so a standalone post-close test pass stays feature-scoped.
+- **Git-build traceability.** `aioson --version` reports `1.34.0 (<sha>, <date>)` from a git checkout (JSON adds `git_sha`/`git_date`); `install`/`update` stamp `template_git_sha`/`template_git_date` into each project's `.aioson/install.json`. Lets a linked dev framework report exactly which commit is installed without a per-commit version bump.
+
+### Fixed
+- **Lean Gate-C dead-end.** The lean lane stalled at `@dev` because no agent produced `spec-{slug}.md`. `@sheldon`'s handoff contract now structurally requires the lean bridge artifacts (spec + approved gates A/B/C + approved implementation-plan + a valid runtime contract).
+- **Runtime-gate coverage at all sizes.** A runtime feature now requires the `RG-*` contract at every classification (was MEDIUM-only), closing the hole where a MICRO/SMALL backend feature closed with prose-only gates.
+- **Cross-platform `sync:agents`.** Replaced the `rsync` step (silently a no-op on Windows) with a Node copy, excluded live project-state from the sync, and preserved the `<!-- AIOSON:BEGIN/END -->` managed block in gateway files (CLAUDE.md / AGENTS.md / OPENCODE.md) instead of stripping it.
+- **Windows `live:start` false "session already active".** `live` now reconciles a dead PID via a `tasklist` probe instead of leaving it `unknown` when `process.kill(pid, 0)` throws `EPERM`.
+
 ## [1.33.1] - 2026-06-24
 
 ### Fixed

package/docs/en/1-understand/ecosystem-map.md

@@ -2,7 +2,7 @@
 
 > **Who this is for:** anyone who wants to see the full team at once.
 > **Reading time:** 8 min
-> **What you'll know after:** who the 29 agents are, when each one enters, and how they communicate.
+> **What you'll know after:** who the 29 agents are, when each one enters, and how they communicate.
 
 ---
 
@@ -27,11 +27,18 @@
         ┌──────────────────────────────────────┐
         │         DEVELOPMENT CORE             │
         │                                      │
-        │  Product → Sheldon → Analyst →       │
-        │  Architect → UX-UI → PM →            │
-        │  Orchestrator → Dev → QA →           │
-        │  Validator → Tester → Pentester      │
+        │  MICRO:  Product → Dev → QA          │
+        │  SMALL:  Product → Sheldon → Dev     │
+        │          → QA                        │
+        │  MEDIUM: Product → Orchestrator      │
+        │          → Dev → Pentester → QA      │
         │                                      │
+        │  Spec sub-agents (opt-in/fan-out):   │
+        │  Analyst · Architect · PM · UX-UI    │
+        │  Scope-Check · Discovery-Design-Doc  │
+        │                                      │
+        │  Post-dev (on demand):               │
+        │  Validator · Tester · Pentester      │
         └──────────────────────────────────────┘
                       │
                       ▼
@@ -68,28 +75,28 @@
 
 ### 2. Development core (official workflow)
 
-The default order depends on the classification:
+The default lane depends on the classification:
 
-**MICRO:** `@setup → @product (optional) → @dev`
-**SMALL:** `@setup → @product → @sheldon (optional) → @analyst → @scope-check → @architect → @dev → @qa`
-**MEDIUM:** `@setup → @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa`
+**MICRO:** `@setup → @product → @dev → @qa`
+**SMALL (lean — default):** `@setup → @product → @sheldon → @dev → @qa`
+**MEDIUM (maestro):** `@setup → @product → @orchestrator → @dev → @pentester → @qa`
 
-> **Why does `@sheldon` appear so early?** It is the **PRD quality guardian** — it runs *between* `@product` and `@analyst` to detect gaps, validate technical assumptions with web research, and decide between enriching the PRD in-place or creating a phased plan in `.aioson/plans/{slug}/`. Can be invoked N times on the same PRD. Skipping this step on serious features is expensive later.
+> **The spec authority changes by size.** For SMALL, `@sheldon` is the **single spec authority** — in one pass it produces requirements + spec (Gates A/B/C approved) + design-doc + readiness + implementation-plan + harness-contract. For MEDIUM, `@orchestrator` is the **maestro** — it fans out `@analyst`/`@architect`/`@pm` (+ `@ux-ui` for UI-heavy) as sub-agents, then consolidates and gates the full spec package. Agents like `@analyst`, `@architect`, `@pm`, `@ux-ui`, `@scope-check`, and `@discovery-design-doc` are **opt-in detours** or **fan-out sub-agents** — none deleted, none invoked by default in the new lanes.
 
 | Agent | What it does | Main output |
 |---|---|---|
 | **`@product`** | Defines vision, scope, feature PRD | `prd.md`, `spec.md` |
-| **`@sheldon`** | PRD quality guardian — gap analysis, web research, sizing, decides in-place vs phased plan | `sheldon-enrichment-{slug}.md` or `.aioson/plans/{slug}/` |
-| **`@analyst`** | Discovers domain, entities, flows in the codebase | `architecture.md`, ER diagrams |
-| **`@architect`** | Technical decisions: structure, libs, integrations | `architecture.md` (decisions) |
-| **`@ux-ui`** | Design system and component specs (MEDIUM) | `design-doc.md`, `discovery.md` |
-| **`@pm`** | Backlog, user stories, ACs (MEDIUM) | `tasks.md`, user stories |
-| **`@orchestrator`** | Coordinates parallel lanes (MEDIUM) | `parallel/`, execution plan |
-| **`@dev`** | Implements the feature | Code + `dev-state.md` |
-| **`@qa`** | Writes tests, validates ACs, autonomous fix cycle (cap 2) | `test-plan.md`, `qa-report-*.md` |
-| **`@validator`** | Technically validates against `harness-contract.json` in a context sandbox | `.aioson/plans/{slug}/last-validator-output.json` (consumed by `harness:apply-validation`, updates `progress.json`) |
-| **`@tester`** | Systematic test engineering (legacy/brownfield) | `test-inventory.md`, coverage tier |
-| **`@pentester`** | Adversarial security review (OWASP, LLM Top 10) | `security-findings-*.json` |
+| **`@sheldon`** | **SMALL single spec authority** — one pass: requirements + spec (Gates A/B/C) + design-doc + readiness + implementation-plan + harness-contract. Also a PRD-hardening / enrichment capability usable in any lane. | `requirements-{slug}.md`, `design-doc-{slug}.md`, `readiness-{slug}.md`, `implementation-plan.md`, `harness-contract.json` |
+| **`@analyst`** | Domain discovery — entities, flows, brownfield mapping. **Opt-in detour / fan-out sub-agent** (invoked by `@orchestrator` in MEDIUM) | `architecture.md`, ER diagrams |
+| **`@architect`** | Technical decisions: structure, libs, integrations. **Opt-in detour / fan-out sub-agent**; runs in **merged mode** (also produces design-doc + readiness) when `@discovery-design-doc` is omitted | `architecture.md` (decisions) |
+| **`@ux-ui`** | UI/UX spec — **opt-in detour** for UI-heavy specs; `@dev` applies design skills directly | `design-doc.md`, `discovery.md` |
+| **`@pm`** | Backlog, user stories, implementation plan (Gate C). **Opt-in detour / fan-out sub-agent** (MEDIUM) | `tasks.md`, user stories |
+| **`@orchestrator`** | **MEDIUM maestro / single spec authority** — fans out `@analyst`/`@architect`/`@pm` (+ `@ux-ui` for UI-heavy) as sub-agents, consolidates the gated spec package. Secondary: coordinate parallel `@dev` lanes post-spec. | `parallel/`, execution plan, consolidated spec package |
+| **`@dev`** | Implements the feature — runs phases as a **loop**: auto-continues between phases, compacts context between phases, per-phase verification (light sub-agent). Full Runtime smoke runs once at end-of-feature. | Code + `dev-state.md` |
+| **`@qa`** | Writes tests, validates ACs, autonomous fix cycle (cap 3), hub of the post-dev autopilot review cycle. Owns Gate D: **Runtime smoke gate** (build + migrations on real DB + boot + Core happy-path on REAL stack). | `test-plan.md`, `qa-report-*.md` |
+| **`@validator`** | Technically validates against `harness-contract.json` in a **fresh isolated context** (detour when a harness contract exists) | `.aioson/plans/{slug}/last-validator-output.json` |
+| **`@tester`** | Systematic test engineering (legacy/brownfield) — triggered by `@qa` when conditions fire | `test-inventory.md`, coverage tier |
+| **`@pentester`** | Adversarial security review (OWASP, LLM Top 10). Inline in MEDIUM; opt-in in SMALL. | `security-findings-*.json` |
 
 ### 3. Continuity and delivery
 
@@ -112,7 +119,7 @@ The default order depends on the classification:
 | **`@design-hybrid-forge`** | Combines two design skills into a hybrid |
 | **`@orache`** | Domain investigation and strategic research |
 | **`@copywriter`** | Conversion copy for landing pages, emails |
-| **`@discovery-design-doc`** | Discovery + design doc combined (joint mode) |
+| **`@discovery-design-doc`** | Discovery + design doc combined — opt-in; absorbed by `@architect` merged mode, `@sheldon`, or `@orchestrator` by default |
 
 ---
 
@@ -207,16 +214,25 @@ You > @product
 @product > Let's start a feature. What's it called? What's the problem?
 You > "checkout-stripe", complete order with card payment.
 @product > [...several questions...] Spec created at context/features/checkout-stripe/spec.md.
-@product > Next: @analyst to map the domain.
+@product > Next: @sheldon to close the spec and produce the implementation package.
 
 ─── Session 2 (next day) ───
 You > @neo
-@neo > You stopped at @product. Next: @analyst.
-You > @analyst
-@analyst > [reads spec.md, examines codebase] Mapped: Order, Customer, Payment, OrderItem.
-@analyst > Decision recorded in architecture.md. Next: @architect.
-
-─── and so on until @qa ───
+@neo > You stopped at @product. Next: @sheldon (single spec authority for SMALL).
+You > @sheldon
+@sheldon > Reading spec.md + codebase... Detected 2 gaps: no idempotency policy on Stripe webhook,
+           no AC for payment failure retry. Researching Stripe docs...
+@sheldon > Spec package ready: requirements, design-doc, readiness (Gate B), implementation-plan (2 phases),
+           harness-contract.json. Gates A/B/C: approved. Next: @dev.
+
+─── Session 3 ───
+You > @dev
+@dev > Reading implementation-plan.md. 2 phases.
+       Phase 1/2: Stripe integration + webhook... harness:check OK. Compacting...
+       Phase 2/2: UI checkout flow... harness:check OK. dev-state.md updated. Next: @qa.
+
+You > @qa
+@qa > 12 ACs. Tests written. 12/12 OK. Runtime smoke: PASS. Feature ready.
 ```
 
 ---

package/docs/en/1-understand/glossary.md

@@ -72,9 +72,9 @@ Terms in alphabetical order. Each entry has a **short definition** + **concrete
 **Definition:** the size of the project, calculated from 3 factors (user types, external integrations, business rules). Determines how much ceremony the workflow applies.
 
 **How it works:**
-- 0–1 points → **MICRO** (`@setup → @product → @dev`)
-- 2–3 points → **SMALL** (`@setup → @product → @analyst → @scope-check → @architect → @dev → @qa`)
-- 4–6 points → **MEDIUM** (full workflow, all gates, all artifacts)
+- 0–1 points → **MICRO** (`@setup → @product → @dev → @qa`)
+- 2–3 points → **SMALL** lean default (`@setup → @product → @sheldon → @dev → @qa`) — `@sheldon` is the single spec authority
+- 4–6 points → **MEDIUM** maestro (`@setup → @product → @orchestrator → @dev → @pentester → @qa`) — `@orchestrator` fans out `@analyst`/`@architect`/`@pm` as sub-agents
 
 **Where it appears:** `classification:` in the `project.context.md` frontmatter.
 
@@ -129,7 +129,7 @@ Terms in alphabetical order. Each entry has a **short definition** + **concrete
 
 **Ready-made examples:** Clean SaaS UI, Aurora Command UI, Cognitive Core UI, Bold Editorial UI, Warm Craft UI, Glassmorphism UI, Neo Brutalist UI.
 
-**Where to choose:** during `aioson init`, in the wizard.
+**Where to choose:** during `aioson init`, in the wizard, or later with `@setup`/`@ux-ui`. The recommended route is the `interface-design` engine driven by your own **reference images**, extracted once into an `identity.md` the engine applies; the presets remain an explicit alternative.
 
 ---
 
@@ -197,7 +197,7 @@ Terms in alphabetical order. Each entry has a **short definition** + **concrete
 
 ## Pipeline / Workflow
 
-**Definition:** the ordered sequence of agents that AIOSON applies to a feature, based on the classification.
+**Definition:** the ordered sequence of agents that AIOSON applies to a feature, based on the classification. Three default lanes exist: MICRO (`@product → @dev → @qa`), SMALL lean (`@product → @sheldon → @dev → @qa`), and MEDIUM maestro (`@product → @orchestrator → @dev → @pentester → @qa`). Spec agents like `@analyst`, `@architect`, `@pm`, and `@ux-ui` are opt-in detours or fan-out sub-agents — not default hops.
 
 **Central command:** `aioson workflow:next .` — shows which agent is next.
 
@@ -255,7 +255,7 @@ Terms in alphabetical order. Each entry has a **short definition** + **concrete
 
 **Example:** a "legal compliance" squad with agents `@regulator`, `@attorney`, `@auditor`, under the command of `@squad`.
 
-**Commands:** `aioson squad:scaffold`, `squad:agent-create`, `squad:doctor`.
+**Commands:** `aioson squad:scaffold`, `squad:agent-create`, `squad:doctor`.
 
 ---
 

package/docs/en/1-understand/what-is-aioson.md

@@ -20,9 +20,9 @@ Imagine you want to build a house.
 
 - **Briefing** listens to your raw idea (the "napkin sketch") and hands back a structured briefing — with risks and open questions — *before* it becomes a project.
 - **Product** understands what you want to build and why — and writes the PRD.
-- **Sheldon** reviews the PRD like a senior architect who has seen everything: points out gaps, researches what's outdated, reads your actual code, and decides whether to enrich the PRD or create a phased plan. Can review multiple times.
-- **Analyst** discovers what already exists in the codebase and what's missing.
-- **Architect** designs the structure.
+- **Sheldon** is the spec authority for SMALL projects: in one pass it closes the PRD, writes the requirements, designs the technical structure, produces the implementation plan, and authors the harness contract. In larger (MEDIUM) projects it hardens the PRD before the full maestro phase.
+- **Analyst** discovers what already exists in the codebase and what's missing (opt-in detour, or fan-out sub-agent in MEDIUM).
+- **Architect** designs the structure (opt-in detour, or fan-out sub-agent in MEDIUM).
 - **UX-UI** designs how the end user will live there.
 - **Dev** builds.
 - **Deyvin** is the site foreman who picks up the job when you return from a trip: reads what's confirmed, flags what's inferred, and proceeds one small step at a time without you having to re-explain anything.
@@ -56,7 +56,7 @@ your-project/
 │   ├── rules/               ← hard rules agents follow (security, etc.)
 │   ├── skills/              ← pluggable packages (design systems, processes)
 │   └── runtime/             ← local telemetry (SQLite)
-├── .claude/  .codex/                         ← native client config
+├── .claude/  .codex/                         ← native client config
 ├── CLAUDE.md  AGENTS.md  OPENCODE.md         ← per-client instructions
 └── docs/                                      ← optional documentation
 ```
@@ -85,7 +85,7 @@ Agents are *prompts*, not plugins. They live in `.md` files and your AI client r
 - **You want to explore an idea freely** in 5 minutes. AIOSON asks for setup first.
 - **You won't open the project again.** The value is precisely in repeated sessions.
 
-For these cases, AIOSON itself has a lightweight path — the **MICRO** classification (`@setup → @product → @dev`). But if even that doesn't fit, don't force it.
+For these cases, AIOSON itself has a lightweight path — the **MICRO** classification (`@setup → @product → @dev → @qa`). But if even that doesn't fit, don't force it.
 
 ## Next step
 

package/docs/en/2-start/existing-project.md

@@ -30,9 +30,9 @@ The interactive wizard appears:
 
 ```
 ? Which AI tools? ›
-   ◉ Claude Code
-   ◉ Codex CLI
-   ◯ OpenCode
+   ◉ Claude Code
+   ◉ Codex CLI
+   ◯ OpenCode
 
 ? Mode? ›
    ◉ Development
@@ -100,8 +100,8 @@ You > Yes — discount policy by customer tier, commission rules
 @setup > project.context.md created with MEDIUM classification.
 @setup > Since you already have running code, I recommend:
         - Run @discover to build the semantic cache
-        - Then @analyst to map the existing domain
-        - Only then start the next feature via @product
+        - Then @analyst to map the existing domain (initial brownfield scan)
+        - Only then start features via @product → @orchestrator (MEDIUM maestro)
 ```
 
 ---
@@ -154,10 +154,10 @@ You > "order-cancellation" — allow canceling an order within 1 hour
 @product > Acceptance criteria?
 You > [...]
 
-@product > Spec saved. Next: @analyst.
+@product > Spec saved. Next: @orchestrator (MEDIUM maestro — will fan out @analyst, @architect, @pm).
 ```
 
-From there the flow is the same as in [first-project.md](./first-project.md).
+From there, the MEDIUM maestro flow applies: `@product → @orchestrator → @dev → @pentester → @qa`. `@orchestrator` fans out `@analyst`, `@architect`, and `@pm` as sub-agents (the domain knowledge from Step 5 feeds into them), consolidates the gated spec package, and hands to `@dev`. See [Full feature with @sheldon — MEDIUM variant](../3-recipes/full-feature-with-sheldon.md#medium-maestro-variant) for the full walkthrough.
 
 ---
 

package/docs/en/2-start/first-project.md

@@ -142,47 +142,37 @@ You'll see a structured spec with scope, ACs, and out-of-scope items.
 
 ---
 
-## Step 5 — `@analyst` maps the domain
+## Step 5 — `@sheldon` closes the spec (single spec authority for SMALL)
 
 ```
-You > @analyst
-
-@analyst > Reading spec... domain: personal tasks.
-@analyst > Entities:
-        - Task { id, text, completed, created_at }
-@analyst > No other entities in scope.
-@analyst > Domain map saved to context/architecture.md.
-@analyst > Next: @architect.
-```
-
----
+You > @sheldon
 
-## Step 6 — `@architect` decides the structure
+@sheldon > Reading spec.md... stack: Node + Express + SQLite.
+@sheldon > No external gaps detected (simple scope). Producing spec package:
+        ✓ design-doc-task-list.md (structure: src/{routes,db,server}.js)
+        ✓ readiness-task-list.md (Gate B: ready)
+        ✓ implementation-plan.md (1 phase — scope is tight)
+        ✓ harness-contract.json (4 RG-smoke criteria matching the ACs)
 
-```
-You > @architect
-
-@architect > Stack confirmed: Node + Express + SQLite.
-@architect > Decisions:
-        - Structure: src/{routes,db,server}.js
+@sheldon > Notes:
         - Persistence: better-sqlite3 (synchronous SQLite, simple)
-        - Validation: small, manual (no extra libs — Article VI)
-        - No heavy test framework: use node:test (built-in)
-@architect > Decisions recorded in architecture.md.
-@architect > Next: @dev.
+        - Validation: manual (no extra libs — Article VI)
+        - Test framework: node:test (built-in, no dependency)
+@sheldon > Gates A/B/C: approved. Next: @dev.
 ```
 
-> **Note Article VI ("Simplicity Over Ceremony"):** `@architect` avoided pulling in unnecessary libraries.
+> **Note Article VI ("Simplicity Over Ceremony"):** `@sheldon` flagged no unnecessary libraries. On a simple project like this it produces a lean package; on a complex feature it would do web research and multi-phase planning.
 
 ---
 
-## Step 7 — `@dev` implements
+## Step 6 — `@dev` implements
 
 ```
 You > @dev
 
-@dev > [reads spec, architecture, project.context]
-@dev > I'll create:
+@dev > [reads implementation-plan.md, spec, project.context]
+@dev > Phase 1/1: full implementation (tight scope).
+@dev > Creating:
         package.json
         src/db.js          (init schema)
         src/routes.js      (POST /tasks, PATCH /tasks/:id, GET /tasks)
@@ -190,8 +180,7 @@ You > @dev
         tests/tasks.test.js (placeholder — @qa covers)
 
 @dev > [implements]
-@dev > Implementation OK. Running smoke:
-        $ node src/server.js → listening on 3000 ✓
+@dev > aioson harness:check → 4/4 criteria pass.
 @dev > dev-state.md updated.
 @dev > Next: @qa.
 ```
@@ -208,7 +197,7 @@ cat .aioson/context/dev-state.md
 
 ---
 
-## Step 8 — `@qa` tests
+## Step 7 — `@qa` tests
 
 ```
 You > @qa
@@ -229,11 +218,11 @@ You > @qa
 @qa > test-plan.md and qa-report.md saved. Feature ready.
 ```
 
-> **What's new:** the *autonomous QA→Dev cycle* (cap 2) lets `@qa` request small fixes without you having to manually reactivate it. Added in May/2026.
+> **What's new:** the *autonomous QA→Dev cycle* (cap 3, `agentic_policy.review_cycle`) lets `@qa` request small fixes without you having to manually reactivate it. Under autopilot, this same cycle can chain all the way to `@tester`/`@pentester`/`@validator` and the `feature:close` recommendation without stopping — see [Autopilot handoff](../5-reference/autopilot-handoff.md).
 
 ---
 
-## Step 9 — Clean commit with `@committer`
+## Step 8 — Clean commit with `@committer`
 
 ```
 You > @committer
@@ -260,14 +249,19 @@ You > [Enter to accept]
 
 ```
 .aioson/context/
-├── project.context.md         ← project view (step 3)
-├── architecture.md            ← decisions (steps 5+6)
-├── dev-state.md               ← what @dev did (step 7)
-├── test-plan.md               ← @qa's plan (step 8)
-├── qa-report-test-coverage.md ← QA report
+├── project.context.md           ← project view (step 3)
+├── design-doc-task-list.md      ← @sheldon spec (step 5)
+├── readiness-task-list.md       ← @sheldon Gate B (step 5)
+├── implementation-plan.md       ← @sheldon (step 5)
+├── dev-state.md                 ← what @dev did (step 6)
+├── test-plan.md                 ← @qa's plan (step 7)
+├── qa-report-test-coverage.md   ← QA report
 └── features/
     └── task-list/
-        └── spec.md            ← original spec (step 4)
+        └── spec.md              ← original spec (step 4)
+
+.aioson/plans/task-list/
+└── harness-contract.json        ← @sheldon success contract
 ```
 
 Three months from now, someone (you or another AI) can open this project and understand **everything** just by reading these files. No chat history needed.
@@ -276,7 +270,7 @@ Three months from now, someone (you or another AI) can open this project and und
 
 ## What if I want a new feature?
 
-Go back to step 4. `@product` creates a new feature → `@analyst` → `@architect` → `@dev` → `@qa`. `@setup` doesn't need to run again (context is already there).
+Go back to step 4. `@product` creates a new feature → `@sheldon` (closes the spec) → `@dev` → `@qa`. `@setup` doesn't need to run again (context is already there).
 
 If you get lost in the middle:
 

package/docs/en/2-start/initial-decisions.md

@@ -28,12 +28,12 @@ The sum of three factors (each worth 0, 1, or 2 points):
 
 ### What changes at each level
 
-#### MICRO — `@setup → @product (optional) → @dev`
+#### MICRO — `@setup → @product → @dev → @qa`
 
 - For: scripts, automations, prototypes, simple personal apps.
-- No `@analyst` or `@architect`. You talk directly to `@dev`.
+- No formal spec phase — no `@sheldon` or `@orchestrator`. Lightweight.
 - `@product` is optional — you can pass the spec directly in chat if you prefer.
-- No `@qa` in the standard flow (you can invoke it manually).
+- No per-phase verification; `@dev` phase checks are suppressed to save tokens.
 
 **Typical examples:**
 - Python script that processes CSV
@@ -41,11 +41,12 @@ The sum of three factors (each worth 0, 1, or 2 points):
 - Static portfolio page
 - Mini API with 3 endpoints
 
-#### SMALL — `@setup → @product → @analyst → @scope-check → @architect → @dev → @qa`
+#### SMALL — `@setup → @product → @sheldon → @dev → @qa` (lean default)
 
 - For: most real apps.
-- Full discovery+development+QA cycle.
-- No `@ux-ui`, `@pm`, or `@orchestrator` in the standard flow (you can invoke them individually).
+- `@sheldon` is the **single spec authority**: in one pass it produces requirements + spec (Gates A/B/C) + design-doc + readiness + implementation-plan + harness-contract, then hands directly to `@dev`.
+- `@analyst`, `@architect`, `@pm`, `@ux-ui`, `@scope-check` are opt-in detours — not in the default hop sequence.
+- `@dev` runs a phase loop: auto-continues between phases, per-phase verification, context compaction.
 
 **Typical examples:**
 - SaaS app for a single persona
@@ -53,12 +54,12 @@ The sum of three factors (each worth 0, 1, or 2 points):
 - Simple online store
 - Blog with admin panel
 
-#### MEDIUM — full workflow
+#### MEDIUM — `@setup → @product → @orchestrator → @dev → @pentester → @qa` (maestro lane)
 
 - For: products with multiple user types, several integrations, complex rules.
-- Adds `@ux-ui`, `@pm`, `@orchestrator`.
+- `@orchestrator` is the **single spec authority**: fans out `@analyst`/`@architect`/`@pm` (+ `@ux-ui` for UI-heavy) as sub-agents, consolidates the gated spec package, then hands to `@dev`.
+- `@pentester` runs inline (not opt-in) before `@qa`.
 - Quality gates applied at each handoff.
-- Parallel lanes possible (`@orchestrator` coordinates).
 - More aggressive context threshold (55% — warns early).
 
 **Typical examples:**
@@ -99,7 +100,7 @@ You can mark **more than one** in the wizard — they coexist in the same projec
 
 ### Development (default)
 
-Includes the 29 official agents (product, analyst, dev, qa, etc.; `@pair` is alias of `@deyvin`). Sufficient for 95% of projects.
+Includes the 29 official agents (product, analyst, dev, qa, etc.; `@pair` is alias of `@deyvin`). Sufficient for 95% of projects.
 
 ### Development + Squads
 
@@ -110,13 +111,13 @@ Adds the squad system — you can create custom squads for domains outside the s
 - `@attorney` — interprets clauses
 - `@auditor` — checks conformity
 
-```bash
-# Inside the AI client
-> @squad scaffold compliance
-
-# Or via CLI
-npx @jaimevalasek/aioson squad:scaffold . --slug=compliance --name="Compliance" --mode=mixed
-```
+```bash
+# Inside the AI client
+> @squad scaffold compliance
+
+# Or via CLI
+npx @jaimevalasek/aioson squad:scaffold . --slug=compliance --name="Compliance" --mode=mixed
+```
 
 **When to activate Squads:**
 - You know you'll need specialization outside the standard
@@ -133,7 +134,9 @@ npx @jaimevalasek/aioson squad:scaffold . --slug=compliance --name="Compliance"
 
 ## Choosing a Design System
 
-Available in the wizard:
+> **Recommended route: `interface-design` + your own reference images.** Instead of inheriting a fixed preset's identical look, you provide reference images (identity/brand and, optionally, component structure); the `reference-identity-extract` skill converts them **once** into a text `identity.md` that the `interface-design` engine applies to everything downstream (prototype and build). `@setup` offers this route first — always with explicit confirmation, never auto-selected. The presets below remain available as an alternative.
+
+Presets available in the wizard:
 
 | Skill | Style | Use cases |
 |---|---|---|
@@ -146,7 +149,7 @@ Available in the wizard:
 | **Neo Brutalist UI** | Black outlines, strong colors, no shadow | Bold brands |
 
 **Skipping** is a valid option. You can:
-- Choose later with `@ux-ui`
+- Choose later with `@ux-ui` — it offers the same two routes (reference images or preset)
 - Clone a real site's design with `@site-forge`
 - Create a hybrid with `@design-hybrid-forge` (e.g., clean-saas + neo-brutalist)
 

package/docs/en/3-recipes/README.md

@@ -8,7 +8,7 @@ These three trails show **how features reach development** in AIOSON. You almost
 
 | Trail | When to use | Key agents |
 |---|---|---|
-| **[Full feature with @sheldon](./full-feature-with-sheldon.md)** | You have a PRD in mind and want the complete canonical trail (most used) | @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa |
+| **[Full feature with @sheldon](./full-feature-with-sheldon.md)** | SMALL lean (default) or MEDIUM maestro — the canonical feature trail | SMALL: `@product → @sheldon → @dev → @qa`; MEDIUM: `@product → @orchestrator → @dev → @pentester → @qa` |
 | [From idea to PRD via @briefing](./from-idea-to-prd-via-briefing.md) | Your idea is still vague, several loose notes | @briefing → @product |
 | [External plans for @product](./external-plans-for-product.md) *(coming soon)* | You already planned in another chat (ChatGPT, Claude.io Web) | @product (reads `/plans/`) |
 
@@ -17,7 +17,7 @@ These three trails show **how features reach development** in AIOSON. You almost
 | Recipe | Scenario | Main agents |
 |---|---|---|
 | [Landing page](./landing-page.md) *(coming soon)* | Create a presentation page with copy and design | @product, @copywriter, @ux-ui, @dev, @qa |
-| [SaaS app from scratch](./saas-app-from-scratch.md) *(coming soon)* | Full SaaS: auth, Stripe billing, admin | Full MEDIUM workflow + @orchestrator |
+| [SaaS app from scratch](./saas-app-from-scratch.md) *(coming soon)* | Full SaaS: auth, Stripe billing, admin | `@product → @orchestrator → @dev → @pentester → @qa` (MEDIUM maestro) |
 | [Integration in large codebase](./integration-in-large-codebase.md) *(coming soon)* | Install AIOSON on a 10k–100k line legacy project | @discover, @analyst |
 | [Large refactor](./large-refactor.md) *(coming soon)* | Rewrite a critical module without breaking anything | @sheldon, @tester, @dev, @qa |
 | [Security audit](./security-audit.md) *(coming soon)* | Review vulnerabilities before production | @pentester |

package/docs/en/3-recipes/continuity-between-sessions.md

@@ -55,7 +55,7 @@ The file has standardized sections:
 slug: checkout-stripe
 status: in_progress
 classification: SMALL
-agents_trail: [@product, @analyst, @architect, @dev]
+agents_trail: [@product, @sheldon, @dev]
 last_agent: @dev
 last_updated: 2026-05-06T14:32:00Z
 
@@ -196,7 +196,7 @@ npx @jaimevalasek/aioson dossier:show --slug=checkout-stripe
 ```
 FEATURE: checkout-stripe
 Status: in_progress
-Agents: @product, @analyst, @architect, @dev, @deyvin
+Agents: @product, @sheldon, @dev, @deyvin
 Progress: 4/5 steps done (80%)
 Files: 5 (3 created, 2 pending)
 Research: 1 (stripe webhooks)