@jaimevalasek/aioson 1.30.2 → 1.36.0

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/autopilot-handoff.md

@@ -1,14 +1,14 @@
 ---
-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 (pre-dev detours → dev → review cycle)
 
 Opt-in protocol that removes manual handoff confirmations in the deterministic segments of the feature workflow. 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.
+1. **Pre-dev chain (opt-in detours → `@dev`):** by default the MEDIUM lane routes `@product → @orchestrator → @dev` and the SMALL lean lane routes `@product → @sheldon → @dev`, so there is no pre-dev auto-chain — `@orchestrator` (maestro) and `@sheldon` (lean) own the spec solo and hand off manually. `@analyst`, `@architect`, `@pm`, `@scope-check`, and `@discovery-design-doc` chain automatically only when an opt-in detour adds them to the active sequence. Upstream agents (`@briefing`, `@product`, `@sheldon`, `@orchestrator`) 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.
 
 ## Activation
@@ -45,13 +45,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 — pre-dev chain (opt-in detours → `@dev`)
 
-SMALL feature: `@analyst` → `@scope-check` → `@architect` → `@discovery-design-doc` → `@dev`.
+SMALL feature (lean default): `@product` → `@sheldon` → `@dev` — `@product`/`@sheldon` hand off manually, so there is no pre-dev auto-chain; autopilot resumes in the post-dev review cycle (Segment 2). 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` — `@product`/`@orchestrator` hand off manually too, so there is likewise no pre-dev auto-chain (the `@orchestrator` maestro fans out to `@analyst`/`@architect`/`@pm` as sub-agents, not as workflow stages). `@analyst` → `@architect` → `@pm` → `@dev` auto-chains only when an opt-in full-chain detour adds those stages to the sequence (`@discovery-design-doc` and `@scope-check` chain only if the sequence adds them).
 
-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.
+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.
 
 ## Segment 2 — post-dev review cycle (hub = `@qa`)
 
@@ -87,12 +87,12 @@ Routing table (each row is followed only when autopilot is active and no stop co
 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.
 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,47 @@
+---
+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 — do NOT stop to ask "continue?" between phases** (`phase_loop.auto_continue` in `.aioson/config/verification.json`). The per-phase verification report replaces that human checkpoint: a clean report means proceed; a failing one stops the loop. Set `auto_continue: false` 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 returned `host` / `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. **Compact between phases** (when `phase_loop.compact_between_phases` is true and phases remain). Write the cold-start packet:
+   ```bash
+   aioson dev:state:write   # slug, completed phase, next phase, manifest path, required context, decisions
+   ```
+   then shed context — `/compact` on Claude Code, or open a fresh context and reload via `aioson dev:resume-data .` on codex/opencode — and resume on the next phase. Each phase gets a clean context with no manual chat hand-off.
+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.
+- Compaction between phases keeps each phase's context small, which is cheaper than carrying one accumulating context across a long feature.
+
+## 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`).

package/template/.aioson/docs/feature-expansion-taxonomy.md

@@ -5,12 +5,12 @@ agents: [briefing, briefing-refiner, product, sheldon]
 modes: [planning, executing]
 task_types: [feature-expansion, product-discovery, prd-enrichment, briefing-refinement]
 load_tier: trigger
-triggers: [feature expansion, rich surface, MVP options, product scope, capability map, Trello, generator, dashboard, workflow, editor, collaboration]
+triggers: [feature expansion, rich surface, MVP options, product scope, capability map, operational surface, CRUD surface, management surface, Trello, Kanban, CRM, workspace, board, dashboard, workflow, editor, collaboration]
 ---
 
 # Feature Expansion Taxonomy
 
-Use this shared vocabulary when a feature has a rich surface: workflow tools, collaboration, editors/builders, generators, media outputs, dashboards, CRM/Kanban-style systems, automation, templates, customization, or repeated operational use.
+Use this shared vocabulary when a feature has a rich surface: workflow tools, collaboration, editors/builders, generators, media outputs, dashboards, CRM/Kanban-style systems, automation, templates, customization, workspaces, boards, operational CRUD, or repeated operational use.
 
 Expansion is not approval. It reveals options, classifies value and risk, and makes scope easier to choose.
 
@@ -41,13 +41,41 @@ Check only lenses relevant to the feature:
 - Integrations and automation: imports, exports, webhooks, scheduled jobs, simple rules.
 - Implementation leverage: framework-native features, low-cost libraries, existing modules.
 
+## Operational Surface Map
+
+For rich-surface products, expansion is incomplete until the main objects have an operational surface map.
+
+Use this table shape:
+
+| Object | Parent / owner | Lifecycle states | Required actions | Management surface | Empty / error states | Permissions / roles |
+|---|---|---|---|---|---|---|
+| Workspace | owner / members | active, archived | create, switch, edit, archive, invite | workspace switcher + workspace settings | no workspaces, invite failed | owner, member |
+
+Rules:
+
+- A named Core object is not real scope until its create, list/view, edit, delete/archive, and restore behavior is either covered or explicitly deferred.
+- Every Core object needs a management surface: page, panel, modal, drawer, inline action, settings screen, or command. If there is no place to manage it, the product is underspecified.
+- Parent/child relationships must be explicit. For Trello-like systems, cards imply lists/columns, boards, workspaces, members, and at least basic role boundaries.
+- A user flow that says "manage cards" is too thin unless it names how the user adds, edits, moves, archives, restores, and sees validation feedback.
+- Empty states and failure states are Core for first-use products, admin surfaces, and repeated-use operational tools.
+- Deferred lifecycle actions must be visible in Out of scope, not silently omitted.
+
+Minimum expected surfaces for Trello/Kanban/CRM/workspace-like products:
+
+- Workspace or account home: create/select workspace, invite/manage members, edit settings.
+- Board/list/index surface: create/select/search/archive boards or pipelines.
+- Main work surface: view columns/lists/status groups, create/move/edit/archive primary items.
+- Item detail surface: edit content, metadata, assignee/owner, labels/status, comments/notes when in scope.
+- Empty/error surfaces: no workspace, no board, no items, permission denied, validation failure.
+
 ## Required Trace
 
 Every expansion artifact should state:
 
 - whether prior expansion artifacts were found
 - which bucket each suggestion belongs to
+- which Core objects were mapped in the operational surface map
+- which management surfaces are required for those Core objects
 - which ideas need explicit user approval
 - which ideas are intentionally deferred
 - how the expansion affects project classification or delivery risk
-

package/template/.aioson/docs/presets/workflow.config.full-merged.json

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "_about": "Full chain with @discovery-design-doc merged into @architect. Copy to .aioson/context/workflow.config.json. When discovery-design-doc is absent from the sequence, @architect runs in merged mode and produces design-doc + readiness + dev-state itself. See .aioson/docs/workflow-lean-lane.md and agents/architect.md (Architect merged mode). Runtime smoke gate stays mandatory.",
+  "feature": {
+    "MICRO": ["product", "dev", "qa"],
+    "SMALL": ["product", "analyst", "scope-check", "architect", "dev", "qa"],
+    "MEDIUM": ["product", "analyst", "architect", "pm", "scope-check", "dev", "pentester", "qa"]
+  },
+  "project": {
+    "MICRO": ["setup", "dev"],
+    "SMALL": ["setup", "product", "analyst", "scope-check", "architect", "dev", "qa"],
+    "MEDIUM": ["setup", "product", "analyst", "architect", "ux-ui", "pm", "orchestrator", "scope-check", "dev", "qa"]
+  },
+  "rules": { "required": ["dev"], "allowDetours": true }
+}

package/template/.aioson/docs/presets/workflow.config.lean.json

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "_about": "Lean lane preset. Copy to .aioson/context/workflow.config.json to opt in. See .aioson/docs/workflow-lean-lane.md. Runtime smoke gate stays mandatory in both lanes.",
+  "feature": {
+    "MICRO": ["product", "dev", "qa"],
+    "SMALL": ["product", "sheldon", "dev", "qa"],
+    "MEDIUM": ["product", "sheldon", "dev", "qa"]
+  },
+  "project": {
+    "MICRO": ["setup", "dev"],
+    "SMALL": ["setup", "product", "sheldon", "dev", "qa"],
+    "MEDIUM": ["setup", "product", "sheldon", "dev", "qa"]
+  },
+  "rules": { "required": ["dev"], "allowDetours": true }
+}

package/template/.aioson/docs/product/prd-contract.md

@@ -1,11 +1,11 @@
----
-description: "Product PRD contract — exact PRD structure, visual identity block, output paths, and next-step routing."
-agents: [product]
-modes: [executing]
-task_types: [prd-writing, prd-finalization, output-contract, artifact-writing]
-load_tier: trigger
-triggers: [writing PRD, updating PRD, PRD contract, output path, next-step routing, visual identity]
----
+---
+description: "Product PRD contract — exact PRD structure, visual identity block, output paths, and next-step routing."
+agents: [product]
+modes: [executing]
+task_types: [prd-writing, prd-finalization, output-contract, artifact-writing]
+load_tier: trigger
+triggers: [writing PRD, updating PRD, PRD contract, output path, next-step routing, visual identity]
+---
 
 # Product PRD Contract
 
@@ -98,15 +98,15 @@ After the PRD is produced:
 | classification | Next step |
 |---|---|
 | MICRO | `@dev` |
-| SMALL | `@analyst` |
-| MEDIUM | `@analyst` then `@architect` → `@ux-ui` → `@pm` → `@orchestrator` |
+| SMALL | `@sheldon` (lean default) |
+| MEDIUM | `@orchestrator` (maestro spec authority) |
 
 ### New feature (`prd-{slug}.md`)
 
 | feature complexity | Next step |
 |---|---|
 | MICRO | `@dev` |
-| SMALL | `@analyst` |
-| MEDIUM | `@analyst` → `@architect` → `@scope-check` → `@dev` → `@qa` |
+| SMALL | `@sheldon` (lean default) |
+| MEDIUM | `@orchestrator` (maestro) → `@dev` → `@pentester` → `@qa` |
 
 Assess feature complexity from the conversation and state the next agent explicitly.

package/template/.aioson/docs/prototype-contract.md

@@ -0,0 +1,98 @@
+---
+name: prototype-contract
+agents: [product, ux-ui, analyst, architect, pm, orchestrator, dev, validator, sheldon]
+modes: [planning, executing]
+task_types: [prd, ui-spec, discovery, requirements, architecture, implementation, validation]
+load_tier: trigger
+triggers: [prototype, prototype.html, prototype reference, app-shell, clickable prototype, casca]
+---
+
+# Prototype Contract
+
+When a feature has a clickable prototype from `prototype-forge` (`@briefing-refiner`), that prototype is the
+authoritative reference for the feature's screens, navigation, and interactions. This doc defines how each
+role uses it so the prototype is honored end-to-end, not lost after refinement.
+
+## Where it lives
+
+- `.aioson/briefings/{slug}/prototype.html` — the clickable app-shell.
+- `.aioson/briefings/{slug}/prototype-manifest.md` — screen inventory, Core interactions demonstrated,
+  `design_skill` used, and lock status.
+
+It is **mock-only**: no backend, refresh resets. Reproduce its behavior against the real stack — never copy
+its mock persistence.
+
+## The PRD pointer
+
+When a prototype exists, `@product` adds a `## Prototype reference` section to the PRD:
+
+```
+## Prototype reference
+- prototype: .aioson/briefings/{slug}/prototype.html
+- manifest: .aioson/briefings/{slug}/prototype-manifest.md
+- status: draft | locked-at: {ref}
+- Treat as the authoritative screen/interaction reference for this feature.
+```
+
+The PRD is the carrier: every downstream agent that reads the PRD discovers the prototype through this section.
+
+## Lock (draft → locked)
+
+The prototype is `draft` while scope is open. When `@product`/`@sheldon` freeze scope, the prototype is
+re-synced to match the final PRD and marked `locked-at: {ref}`. The locked version is what implementation
+reproduces and what acceptance criteria are derived from. If the PRD and a `draft` prototype diverge at lock,
+the approved PRD wins and the prototype is updated to match.
+
+## Role usage
+
+- **@product** — write the `## Prototype reference` section; keep the PRD consistent with the prototype; mark
+  it `locked` at scope freeze.
+- **@sheldon** — when enriching a PRD that carries a `## Prototype reference`, keep the enrichment and any
+  phased plan consistent with the prototype's screens and Core interactions; do not silently enrich away a
+  demonstrated interaction. Co-own the `draft → locked` scope freeze with `@product`; if enrichment must
+  change a prototyped behavior, record it as an explicit scope decision in the PRD, not a silent drop.
+- **@ux-ui** — the prototype is the concrete realization of the design direction. Use it as the authoritative
+  screen/interaction/visual reference; the `ui-spec` must not contradict it. Refine visual detail on top of
+  it, never around it.
+- **@analyst** — turn the prototype's Core screens and interactions into explicit acceptance criteria in
+  `requirements-{slug}.md` (e.g. "add card persists and re-renders", "board has a management surface"). This
+  is how the prototype reaches `@validator` — as binary criteria, not as a file it reads.
+- **@architect / @pm / @orchestrator** — read the prototype + manifest as the reference for screens, flows,
+  entities, and scope when planning; do not plan a Core surface the prototype omits without saying so.
+- **@dev** — the prototype is the development source for UI and interactions. Reproduce its screens and Core
+  interactions against the real stack. Never ship a Core action the prototype demonstrates (e.g. "add card",
+  "create board", "manage members") while the build lacks it.
+- **@qa** — for a feature with a prototype, the Core interactions are verified through the **Runtime smoke
+  gate**: build + migrate-apply + boot + Core happy-path on the running stack, with the aios-qa browser report
+  (`aioson qa:run`/`qa:scan`) required, not optional. Source inspection ("the API call appears in the source")
+  is **not** parity evidence.
+- **@validator** — verifies prototype-derived acceptance criteria as part of the normal binary contract in
+  `harness-contract.json`. It does **not** read the prototype's behavior to judge the product; but at its
+  **Contract-integrity precheck** it reads `prototype-manifest.md` solely to confirm the contract carries the
+  §2c runtime-gate criteria (`RG-build`/`RG-migrate`/`RG-boot`/`RG-smoke`) for the Core interactions. A runtime
+  feature whose contract has no `RG-*` criteria is rejected (`ready_for_done_gate: false`) before scoring.
+
+## Completeness
+
+A feature with a prototype is not "ready for done" until every Core screen and interaction the prototype
+demonstrates is either **built and verified on the running stack**, or explicitly deferred in the PRD's
+`## Out of scope`.
+
+**Parity is proven by running, not by reading.** A Core interaction counts as built only when it works end to
+end against the real backend/DB — never when a source-string assertion shows the API call *appears* in the
+code, and never when a structural "parity" unit test passes. The prototype is mock-only; the implementation
+must reproduce its behavior on a booted, migrated stack. This is enforced by `@qa`'s **Runtime smoke gate** and
+the `RG-build`/`RG-migrate`/`RG-boot`/`RG-smoke` criteria in `harness-contract.json` (see
+`harness-contract.md` §2c).
+
+## Deterministic guard
+
+Run `aioson prototype:check . --feature={slug}` once `@analyst` has written `requirements-{slug}.md`. It is the
+deterministic backstop for this otherwise prose-only contract and fails on: a dangling `## Prototype reference`
+(prototype or manifest file missing), a missing requirements bridge, or Core interactions listed in the manifest
+that no acceptance criterion echoes (`fail` = none covered, `warn` = some uncovered). It matches interaction
+names as folded substrings, so the AC must echo the manifest's interaction name (EN or pt-BR). The check never
+reads the prototype's behavior — only that the contract's structural links exist end to end. It is a
+*structural* backstop, **not** runtime proof: an AC that merely echoes an interaction name still has to be
+verified on the running stack by `@qa`'s Runtime smoke gate. Passing `prototype:check` never means a Core
+interaction actually works.