@jaimevalasek/aioson 1.30.2 → 1.36.0

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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
+- **Hardened adversarial verification gates.** `prototype:check` now rejects prototype and manifest references that resolve outside the project root before reading them, strict evidence bundles run prototype checks with `--strict`, partial prototype acceptance-criterion coverage can fail strict audits, Sheldon-owned scope findings route back to `@sheldon`, and failed external auditor stderr is kept in a separate artifact instead of being copied into the consolidated verification report.
+
+## [1.33.0] - 2026-06-24
+
+### Changed
+- **Scope-aware solution fan-out in `@briefing`.** Horizontal exploration no longer forces 3–5 options when the user has already committed to one specific solution and its operational surface is complete; it records any weighed alternative as a short "Alternatives considered" note instead. Operational completeness is never waived — only the breadth of options when the direction is already fixed.
+- **Non-blocking prototype recommendation in `@briefing-refiner`.** For a rich-surface briefing with no prototype yet, the handoff now recommends running prototype mode before `@product` (it surfaces missing management screens and broken interactions early). Recommendation only — it never blocks the route to `@product`.
+
+## [1.32.0] - 2026-06-24
+
+### Added
+- **External DESIGN.md sources in `@design-hybrid-forge`.** A hybrid's primary parent or modifier can now be an external DESIGN.md source (a refero.design md-example or a similar portable design spec extracted from a real site), not only a local AIOSON design skill. The agent normalizes the source into the same parent DNA the crossover protocol expects, records `sources[]` provenance in `.skill-meta.json`, and enforces an anti-clone rule — the hybrid stays a new identity (no brand/logo/trademark or 1:1 palette reproduction, never named after the source). The "exactly 2 primary parents" model is unchanged.
+
+## [1.31.0] - 2026-06-24
+
+### Added
+- **Clickable prototype stage.** New `prototype-forge` process skill and an optional `@briefing-refiner` "Generate prototype" mode produce a self-contained, clickable HTML app-shell (`prototype.html` + manifest) that materializes a rich-surface feature's screens, navigation, and CRUD interactions before the PRD — delegating visuals to the selected design skill while owning structure, behavior, and state. No native dialogs; authenticated app chrome is seeded.
+- **Horizontal solution exploration in `@briefing`.** For goals with more than one viable shape, `@briefing` explores 3–5 solution shapes, maps each one's operational surface, and writes an optional `solution-options.md` so `@product` chooses with the trade-offs in hand.
+- **Prototype propagated as a contract.** New `prototype-contract.md` defines how the prototype flows through the chain: `@product` writes a `## Prototype reference` in the PRD, `@dev` reproduces its screens/interactions, `@ux-ui` treats it as the authoritative realization, and `@analyst` derives acceptance criteria so `@validator` honors it via the binary contract (respecting its context sandbox).
+- **Operational-surface classification floor.** `aioson classify` now floors rich operational surfaces (workspaces, boards/cards, Kanban/CRM pipelines, CRUD/admin management) to at least SMALL, so a Trello-like feature can't take the MICRO shortcut that skips `@analyst`/`@architect`/the prototype.
+
+### Changed
+- **Operational Surface Map across planning agents.** `feature-expansion-taxonomy.md` and the briefing/product/sheldon expansion skills now require every Core object to have create/list/edit/archive/restore behavior and a management surface, so rich-surface features (Trello/Kanban/CRM/workspace-like) can't pass with bare nouns.
+
 ## [1.30.2] - 2026-06-24
 
 ### Changed

package/README.md

@@ -716,7 +716,7 @@ aioson scan:project [path] [--folder=src] [--with-llm] [--provider=<name>] [--dr
 aioson agents
 aioson agent:prompt <agent> [--tool=codex|claude|gemini|opencode]
 aioson workflow:plan [path] [--classification=MICRO|SMALL|MEDIUM] [--json]
-aioson workflow:next [path] [--complete] [--auto-heal] [--force]
+aioson workflow:next [path] [--complete] [--auto-heal] [--force] [--scope-mode=post-dev|post-fix|final] [--verification-policy=advisory|standard|strict]
 aioson workflow:heal [path] --stage=<agent>
 aioson workflow:harden [path] [--dry-run]
 aioson workflow:execute [path] [--dry-run] [--start-from=<agent>]
@@ -729,8 +729,13 @@ aioson intake:ask [path] --agent=<agent> --schema=<questions.json> [--out=<answe
 <summary><strong>SDD automation & gates</strong></summary>
 
 ```bash
-aioson preflight [path] [--json]
+aioson preflight [path] [--json]
 aioson classify [path] [--json]
+aioson prototype:check [path] --feature=<slug> [--json]
+aioson verify:implementation [path] --feature=<slug> --prepare-ledger|--check-ledger|--build-prompt|--check-report=<path> [--policy=advisory|standard|strict] [--json]
+aioson verify:implementation [path] --feature=<slug> --tool=codex|claude|opencode [--model=<model>|configured-default] [--timeout-ms=<ms>] [--max-output-bytes=<bytes>] [--policy=advisory|standard|strict] [--json]
+aioson harness:retro [path] --feature=<slug>|--last=<N> [--json]
+aioson harness:retro-promote [path] --feature=<slug> [--to=learnings|rules] [--apply --select=<candidate-key|all>] [--json]
 aioson gate:check [path] --gate=A|B|C|D [--json]
 aioson artifact:validate [path] --feature=<slug> [--json]
 aioson ac:test-audit [path] --feature=<slug> [--json]
@@ -738,10 +743,18 @@ aioson sdd:benchmark [path] --feature=<slug> [--json]
 aioson detect:test-runner [path] [--json]
 aioson agent:audit [path] [--json]
 aioson brief:gen [path] --feature=<slug> [--json]
-aioson verify:gate [path] --feature=<slug> [--json]
-```
-
-</details>
+aioson verify:gate [path] --feature=<slug> [--json]
+```
+
+`verify:implementation` prepares/checks `.aioson/context/features/{slug}/implementation-ledger.md`, builds clean-auditor prompt packages, validates `Machine Report` JSON with reusable schema helpers in `src/verification/schema.js`, and can optionally run a constrained auditor through `codex`, `claude`, or `opencode`. Runner execution is opt-in, uses explicit timeout/output limits, writes raw output under `verification-runs/`, and promotes only a valid or system-generated `INCONCLUSIVE` report to `verification-report.md`.
+
+`workflow:next --agent=scope-check --scope-mode=post-dev --verification-policy=strict` consumes an existing local `verification-report.md` as structured evidence in the scope-check prompt. It validates and routes the report result, but never runs an external `--tool` auditor automatically.
+
+`harness:retro` mines schema-valid implementation verification reports as a retrospective source. It uses only non-confirming `Machine Report` findings (`DOES_NOT_CONFIRM`, `PARTIAL`, `NOT_VERIFIED`) and never includes raw auditor output, stderr, prompt packages, or finding evidence text in the generated dossier.
+
+`harness:retro-promote` is the human-approved promotion path from a generated retro dossier to `.aioson/learnings/` or `.aioson/rules/`. It is dry-run by default; writing requires `--apply --select=<candidate-key|all>`. Promotion records bounded metadata and source paths only, and never edits prompts, skills, PRDs, plans, raw reports, or agent files automatically.
+
+</details>
 
 <details>
 <summary><strong>Parallel orchestration</strong></summary>

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 2). 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.
 
@@ -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
@@ -233,7 +222,7 @@ You > @qa
 
 ---
 
-## 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

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)