@jaimevalasek/aioson 1.22.0 → 1.23.1

package/template/.aioson/agents/scope-check.md

@@ -18,13 +18,13 @@ Default to `pre-dev` unless activation context, handoff, or user request says ot
 | `post-fix` | optional after QA/tester/pentester caused code changes | approved plan + findings vs fix diff | whether corrections preserved scope |
 | `final` | optional before close/commit/release | intent vs plan vs delivered result | concise delivery reconciliation |
 
-Recommended workflow:
-
-```
-SMALL:  @product -> @analyst -> @scope-check(pre-dev) -> @architect -> @discovery-design-doc -> @dev -> [@scope-check(post-dev) optional] -> @qa
-MEDIUM: @product -> @analyst -> @architect -> @discovery-design-doc -> @scope-check(pre-dev) -> @dev -> [@scope-check(post-dev) optional] -> @pentester -> @qa
-After QA/tester/pentester fixes: [@scope-check(post-fix) optional] only when code or behavior changed materially.
-```
+Recommended workflow:
+
+```
+SMALL:  @product -> @analyst -> @scope-check(pre-dev) -> @architect -> @discovery-design-doc -> @dev -> [@scope-check(post-dev) optional] -> @qa
+MEDIUM: @product -> @analyst -> @architect -> @discovery-design-doc -> @pm -> @scope-check(pre-dev) -> @dev -> [@scope-check(post-dev) optional] -> @pentester -> @qa
+After QA/tester/pentester fixes: [@scope-check(post-fix) optional] only when code or behavior changed materially.
+```
 
 ## Required input
 
@@ -34,16 +34,19 @@ After QA/tester/pentester fixes: [@scope-check(post-fix) optional] only when cod
 - The selected mode (`pre-dev` default, or `post-dev`/`post-fix`/`final`) — determines which of the above are compared
 > Pick the highest-authority source per claim — see the **Evidence** section below.
 
-## Project Rules, Docs & Design Governance
-
-Check silently and load only what is relevant:
-
-1. `.aioson/rules/` — universal rules or `agents:` including `scope-check`.
-2. `.aioson/docs/` — docs whose `description` matches the active feature or artifact.
-3. `.aioson/context/design-doc*.md` and `.aioson/design-docs/*.md` — when structure, naming, reuse, UI, or implementation path matters.
-4. `.aioson/skills/process/aioson-spec-driven/SKILL.md` — for spec workflows; then load only `references/artifact-map.md` and `references/approval-gates.md` unless a specific reference is needed.
-
-Load other skills on demand. Do not bulk-load.
+## Context Loading Modes
+
+- **PLANNING** — inspect workflow status, selected mode, project context, feature/frontmatter, artifact presence, and `context:select` output. Do not bulk-load rules/docs/design governance.
+- **EXECUTING** — before writing or patching `scope-check*.md` or `dev-state.md`, run `context:select --mode=executing` and load only selected rules/docs/design governance plus the source artifacts needed for the comparison.
+
+Load `aioson-spec-driven/SKILL.md` for spec workflows, then only `references/artifact-map.md` and `references/approval-gates.md` unless a specific reference is needed.
+
+Before optional deep loads, run:
+
+```bash
+aioson context:select . --agent=scope-check --mode=planning --task="<scope-check mode and feature>" --paths="<known artifacts>"
+aioson preflight:context . --agent=scope-check --mode=planning --task="<scope-check mode and feature>" --paths="<known artifacts>"
+```
 
 ## Evidence
 
@@ -146,13 +149,33 @@ Why: {reason}
 Optional handoff: {when useful, suggest `@scope-check --scope-mode=post-dev|post-fix|final`; otherwise "none"}
 ```
 
-## Handoff Rules
-
-- `approved` or `patched`: continue to the next workflow stage.
+## Handoff Rules
+
+- `approved` or `patched`: continue to the next workflow stage.
 - `needs-*`: do not continue downstream; route to the owner with exact files and changes needed.
 - `blocked`: ask one specific question.
 - `post-dev` can route to `@qa` or `@pentester` only when drift is resolved.
-- `post-fix` can route to `@qa` when verification owns the final decision.
+- `post-fix` can route to `@qa` when verification owns the final decision.
+
+## Dev-State Producer
+
+In `pre-dev` mode, when the verdict is `approved` or `patched` and the next workflow stage is `@dev`, write the final cold-start handoff before `agent:epilogue`/`agent:done`:
+
+```bash
+aioson dev:state:write . --feature={slug} --phase=1 \
+  --next="<first concrete implementation slice from scope-check + plan/readiness>" \
+  --context=spec,design-doc,readiness
+```
+
+For MEDIUM features with `implementation-plan-{slug}.md`, use:
+
+```bash
+aioson dev:state:write . --feature={slug} --phase=1 \
+  --next="<first phase from implementation-plan-{slug}.md>" \
+  --context=spec,impl-plan,readiness
+```
+
+If the first implementation slice is UI/frontend work, replace the least relevant optional token with `ui-spec`. Keep the package short; `implementation-plan-{slug}.md` carries phase-triggered loads for requirements, architecture, UI spec, and PRD sections.
 
 ## Autopilot Handoff
 
@@ -171,6 +194,5 @@ If `auto_handoff: true` in `project.context.md` frontmatter, a feature workflow
 At session end:
 
 ```bash
-aioson pulse:update . --agent=scope-check --feature={slug} --action="Scope check {mode}: {status}" --next="{next agent}" 2>/dev/null || true
-aioson agent:done . --agent=scope-check --summary="Scope check {slug}: {mode}/{status}" 2>/dev/null || true
-```
+aioson agent:epilogue . --agent=scope-check --feature={slug} --summary="Scope check {slug}: {mode}/{status}" --action="Scope check {mode}: {status}" --next="{next agent}" 2>/dev/null || aioson agent:done . --agent=scope-check --summary="Scope check {slug}: {mode}/{status}" 2>/dev/null || true
+```

package/template/.aioson/agents/sheldon.md

@@ -274,6 +274,19 @@ Goal: convert binary ACs from the enriched PRD into a machine-checkable contract
 
 Load `.aioson/docs/sheldon/harness-contract.md` for the full procedure: init via `aioson harness:init`, criteria population (binary vs advisory), `contract_mode`/governor selection by risk, and canonical schemas. Mention the contract path in the post-enrichment handoff; the user approves before the contract is final.
 
+## Retro dossier analysis (on-demand)
+
+Load this mode only when the user points you at a retrospective dossier produced by `aioson harness:retro` (`.aioson/context/retro/{slug}.md` or `window-last-{N}.md`). The CLI mines deterministically and materializes the dossier; YOU do the semantic analysis and propose deltas. The dossier is your evidence boundary.
+
+Procedure:
+1. Read the dossier. Only "Propostas candidatas" are eligible for a delta proposal; "Observações" are single-occurrence signals you may cite but must never promote on their own.
+2. Promote an Observação to a proposal ONLY when you can name ≥2 concrete occurrences (feature + finding-ID + path) already present in the dossier. Never invent occurrences the dossier does not list.
+3. Classify the recurring failure classes by citing the dossier's exact occurrences — never re-mine the codebase, run web searches, or call an LLM to "find more". The CLI already did the deterministic mining.
+4. Land accepted deltas EXCLUSIVELY in `.aioson/learnings/` (project gotchas/recipes) and `.aioson/rules/` (agent-loaded rules). Never edit code, specs, or other context files from this mode.
+5. Human approval is mandatory before any delta is written; auto-application is prohibited.
+
+If the dossier is empty (no candidates and no observations), say so and stop — do not fabricate retrospective conclusions.
+
 ## Hard constraints
 - **Never implement code** — role is exclusively PRD analysis and enrichment
 - **Never rewrite Vision, Problem, Users** — those sections belong to `@product`

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

@@ -181,6 +181,15 @@ Work module by module in priority order from the risk map:
 - If code under test has a real bug: report it in `test-plan.md`, do not fix silently
 - Do not modify production code (even small "just to make it testable" changes) — report untestable code instead
 
+**Large test logs — preview, not dump:** when a run emits a big log, redirect it to a file and read a preview + pointer instead of pasting the full output into context:
+
+```bash
+npm test > test-run.log 2>&1 || true
+aioson harness:preview test-run.log --max-bytes=8192
+```
+
+`harness:preview` is read-only (persist-first) and returns the first bytes plus a pointer to the full file. Open the full log only when the preview is insufficient.
+
 ## 4-Tier Verification Protocol (goal-backward)
 
 Verification starts from the goal - what the system must deliver - and works backward.
@@ -651,9 +660,9 @@ function testFuzz_transferNeverExceedsBalance(uint256 amount) public {
 
 If new tests expose a behavior gap that causes `@dev` to change product behavior or implementation scope, recommend optional `@scope-check --scope-mode=post-fix` before final QA. Do not recommend it for test-only additions that confirm the approved behavior.
 
-## Project pulse update (run before session registration)
-
-Update the project pulse via CLI: `aioson pulse:update . --agent=tester --feature={slug} --action="<test results summary>" --next="@qa for formal review or @dev for fixes" 2>/dev/null || true`
+## Project pulse update (run at session close)
+
+Prefer the consolidated epilogue in the "At session end" section. It updates pulse and session registration together.
 
 If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manually:
 1. Set `updated_at`, `last_agent: tester`, `last_gate` in frontmatter
@@ -661,8 +670,22 @@ If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manu
 3. Add entry to "Recent activity" (keep last 3 only)
 4. Update "Next recommended action" — typically @qa for formal review or @dev for fixes
 
-## At session end
-Register: `aioson agent:done . --agent=tester --summary="<one-line summary>" 2>/dev/null || true`
+## At session end
+Register: `aioson agent:epilogue . --agent=tester --feature={slug} --summary="<one-line summary>" --action="<test results summary>" --next="@qa for formal review or @dev for fixes" 2>/dev/null || aioson agent:done . --agent=tester --summary="<one-line summary>" 2>/dev/null || true`
+
+When dev-owned blocking gaps exist, start the runtime-managed correction cycle before invoking `@dev`:
+```bash
+aioson review-cycle:advance . --feature={slug} --plan=.aioson/context/test-plan.md --source=tester --to=dev --json 2>/dev/null || true
+```
+If the action is `invoke_dev`, invoke `Skill(aioson:agent:dev)` with the returned `task`; if it is `stop_cycle_limit`, stop and request human intervention.
+
+## Autopilot handoff (post-dev cycle)
+
+When `auto_handoff: true` is set in `project.context.md`, after the suite is delivered and `agent:epilogue`/`agent:done` is registered, return to the hub instead of stopping (`.aioson/docs/autopilot-handoff.md`):
+- Dev-owned blocking gaps found (failing must-have test, real bug reported) → `Skill(aioson:agent:dev)` with `"fix @tester findings — autopilot handoff"`.
+- Otherwise → `Skill(aioson:agent:qa)` with `"re-evaluate after @tester — autopilot handoff"`.
+
+Emit `Autopilot: @tester → invoking @<next> (Ctrl+C to interrupt)` first. Never auto-run `feature:close`. If `auto_handoff` is absent or `false`, hand off manually (recommend `@qa` or `@dev`).
 
 ## Continuation Protocol
 

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

@@ -5,19 +5,14 @@
 ## Mission
 Produce UI/UX that makes the user proud to show the result. Generic output is failure.
 
-## Project rules, docs & design docs
-
-These directories are **optional**. Check silently. If a directory is absent or empty, move on without mentioning it.
-
-1. **`.aioson/rules/`** — If `.md` files exist, read each file's YAML frontmatter:
-   - If `agents:` is absent → load (universal rule).
-   - If `agents:` includes `ux-ui` → load. Otherwise skip.
-   - Loaded rules **override** the default conventions in this file.
-2. **`.aioson/docs/`** — If files exist, load only those whose `description` frontmatter is relevant to the current task, or that are explicitly referenced by a loaded rule.
-3. **`.aioson/context/design-doc*.md`** — If `design-doc.md` or `design-doc-{slug}.md` files exist, read each file's YAML frontmatter:
-   - If `agents:` is absent → load when the `scope` or `description` matches the current task.
-   - If `agents:` includes `ux-ui` → load. Otherwise skip.
-   - Design docs provide architectural decisions, technical flows, and implementation guidance — use them as constraints, not suggestions.
+## Context loading modes
+
+Use two explicit modes so visual work loads the right evidence without pulling every UX module.
+
+- **PLANNING** — inspect project context, design skill field, PRD/frontmatter, active feature/dossier, artifact presence, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/ux-ui/`, `.aioson/design-docs/`, or design skills.
+- **EXECUTING** — after deriving the primary operation, run `context:select --mode=executing` and load only selected rules/design docs plus the required UX modules for that operation.
+
+Rules and design docs override this file only when selected by metadata, operation trigger, path match, or explicit artifact reference.
 
 ## Step 0 — Design skill gate
 
@@ -42,13 +37,20 @@ Apply when `project_type=site` and the operation is `default-create` or `refine-
 3. **If present:** read the copy file before any layout decision. The page structure (sections, headings, CTAs) must mirror the structure declared in the copy document. Treat the copy as the source of truth for textual content — never paraphrase, never insert placeholders, never reorder sections without the user's explicit instruction.
 4. The `audit`, `research`, `tokens`, `component-map`, and `a11y` submodes do not trigger this gate. They may run on existing UI without copy.
 
-## Required input
-- `.aioson/context/project.context.md`
-- `.aioson/context/prd.md` or `prd-{slug}.md` when present
-- `.aioson/context/discovery.md` when present
-- `.aioson/context/architecture.md` when present
-- `.aioson/context/spec-{slug}.md` (feature mode, if present)
-- `.aioson/context/spec.md` (project mode, if present)
+## Required input
+- `.aioson/context/project.context.md`
+- `.aioson/context/prd.md` or `prd-{slug}.md` when present
+- `.aioson/context/discovery.md` when selected because current flows/entities affect UI
+- `.aioson/context/architecture.md` when selected because component boundaries, routes, or frontend architecture affect UI
+- `.aioson/context/spec-{slug}.md` (feature mode, if present)
+- `.aioson/context/spec.md` (project mode, if present)
+
+Before loading optional inputs, run:
+
+```bash
+aioson context:select . --agent=ux-ui --mode=planning --task="<ux task>" --paths="<known UI paths>"
+aioson preflight:context . --agent=ux-ui --mode=planning --task="<ux task>" --paths="<known UI paths>"
+```
 
 ## Sheldon plan detection (RDA-03)
 
@@ -128,7 +130,7 @@ Before acting, derive one primary `operation`:
 - `component-map`
 - `a11y`
 
-Then build `required_modules` using this map:
+Then build `required_modules` using this map:
 
 | Condition | Required modules |
 |---|---|
@@ -140,14 +142,15 @@ Then build `required_modules` using this map:
 | `component-map` | `.aioson/docs/ux-ui/component-map.md` |
 | `a11y` | `.aioson/docs/ux-ui/accessibility-audit.md` |
 
-Preflight rules:
-
-1. If the operation creates or revises visual direction, load `design-gate.md` before layout or token decisions.
-2. If the operation is `default-create` or `refine-spec`, run the entry check from `design-execution.md` before producing output.
+Preflight rules:
+
+1. If the operation creates or revises visual direction, load `design-gate.md` before layout or token decisions.
+2. If the operation is `default-create` or `refine-spec`, run the entry check from `design-execution.md` before producing output.
 3. If existing UI artifacts are found and the user chooses **Audit**, switch the operation to `audit`.
 4. If the user chooses **Rebuild**, confirm overwrite before continuing.
-5. Do not proceed until every required module has been loaded.
-6. Do not preload ux-ui modules that are not required.
+5. Do not proceed until every required module has been loaded.
+6. Do not preload ux-ui modules that are not required.
+7. Before writing `ui-spec.md`, run `context:select --mode=executing` with the UI paths/components being specified and load only the selected rules/design governance.
 
 ## Output contract
 
@@ -156,9 +159,11 @@ Preflight rules:
 - `.aioson/context/ui-spec.md`
 - `.aioson/context/project.context.md` only if the `design_skill` selection was confirmed in this session
 
-**Creation mode — `project_type≠site`:**
-- `.aioson/context/ui-spec.md`
-- `.aioson/context/project.context.md` only if the `design_skill` selection was confirmed in this session
+**Creation mode — `project_type≠site`:**
+- `.aioson/context/ui-spec.md`
+- `.aioson/context/project.context.md` only if the `design_skill` selection was confirmed in this session
+
+`ui-spec.md` is the canonical downstream UI artifact. `@dev` reads it only when implementing UI components, frontend routes, interaction states, copy placement, or visual QA fixes.
 
 **Submode outputs:**
 - `research` → `.aioson/context/ui-research.md`
@@ -192,4 +197,4 @@ Do not overwrite sections owned by `@product` or `@analyst`.
 - If `aioson` CLI is not available, write a devlog at session end following `.aioson/config.md`.
 
 ## Observability
-At session end, register: `aioson agent:done . --agent=ux-ui --summary="UI spec <slug>: <N> components, design=<skill>" 2>/dev/null || true`
+At session end, prefer: `aioson agent:epilogue . --agent=ux-ui --feature=<slug> --summary="UI spec <slug>: <N> components, design=<skill>" 2>/dev/null || aioson agent:done . --agent=ux-ui --summary="UI spec <slug>: <N> components, design=<skill>" 2>/dev/null || true`

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

@@ -100,8 +100,16 @@ aioson dossier:add-finding . --slug={slug} --agent=validator --section="Agent Tr
 
 Skip silently when the dossier is absent — `progress.json` remains the canonical machine output.
 
-## Observability
-At session end, register: `aioson agent:done . --agent=validator --summary="Validated <slug> phase <N>: score=<0|1>, ready_for_done=<bool>" 2>/dev/null || true`
+## Observability
+At session end, register: `aioson agent:epilogue . --agent=validator --feature=<slug> --summary="Validated <slug> phase <N>: score=<0|1>, ready_for_done=<bool>" --no-dossier 2>/dev/null || aioson agent:done . --agent=validator --summary="Validated <slug> phase <N>: score=<0|1>, ready_for_done=<bool>" 2>/dev/null || true`
+
+## 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"`.
+- 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.
 
 ---
 ## ▶ Next step

package/template/.aioson/config/autonomy-protocol.json

@@ -32,6 +32,7 @@
         "workflow:status",
         "runtime:emit",
         "agent:done",
+        "review-cycle:status",
         "brain:query",
         "doctor"
       ]
@@ -48,6 +49,10 @@
         "memory:trim",
         "workflow:next",
         "workflow:heal",
+        "agent:epilogue",
+        "review-cycle:advance",
+        "review-cycle:resolve",
+        "review-cycle:reset",
         "live:handoff",
         "live:close",
         "dossier:add-codemap",
@@ -56,8 +61,10 @@
         "notify"
       ],
       "write_paths": [
+        ".aioson/context/**",
         ".aioson/context/bootstrap/**",
         ".aioson/context/features/**",
+        ".aioson/plans/**",
         ".aioson/runtime/**"
       ]
     },

package/template/.aioson/design-docs/code-reuse.md

@@ -1,12 +1,17 @@
 ---
-description: "DRY principles, reuse hierarchy, and composition patterns"
-scope: "governance"
-agents: []
----
+description: "DRY principles, reuse hierarchy, and composition patterns"
+scope: "governance"
+agents: [dev, deyvin, architect]
+modes: [planning, executing]
+task_types: [implementation-architecture, file-creation, refactor, reuse]
+load_tier: trigger
+triggers: [creating files, adding shared utility, reusing code, avoiding duplication, extending existing module]
+paths: [src/**, app/**, lib/**, template/**]
+---
 
 # Code Reuse — Governance Rules
 
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+> Loaded by the context selector when creating files, reusing code, extending modules, or avoiding duplication is in scope. Override per-project via `.aioson/rules/`.
 
 ## Before creating any new file
 

package/template/.aioson/design-docs/componentization.md

@@ -1,12 +1,17 @@
 ---
-description: "When and how to extract components, modules, and abstractions"
-scope: "governance"
-agents: []
----
+description: "When and how to extract components, modules, and abstractions"
+scope: "governance"
+agents: [dev, deyvin, architect]
+modes: [planning, executing]
+task_types: [implementation-architecture, module-boundary, refactor, extraction]
+load_tier: trigger
+triggers: [extract component, extract module, split module, abstraction, componentization, refactor duplicated logic]
+paths: [src/**, app/**, lib/**, template/**]
+---
 
 # Componentization — Governance Rules
 
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+> Loaded by the context selector when extraction, module boundaries, duplication, or abstraction decisions are in scope. Override per-project via `.aioson/rules/`.
 
 ## When to extract
 

package/template/.aioson/design-docs/file-size.md

@@ -1,12 +1,17 @@
 ---
-description: "File size guidelines, alert thresholds, and split strategies"
-scope: "governance"
-agents: []
----
+description: "File size guidelines, alert thresholds, and split strategies"
+scope: "governance"
+agents: [dev, deyvin, architect]
+modes: [planning, executing]
+task_types: [implementation, refactor, extraction, file-size]
+load_tier: trigger
+triggers: [large file, over 500 lines, split file, extract module, file size, growing file]
+paths: [src/**, app/**, lib/**, template/**, tests/**]
+---
 
 # File Size — Governance Rules
 
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+> Loaded by the context selector when file size, split, extraction, or large-file risk is in scope. Override per-project via `.aioson/rules/`.
 
 ## Thresholds
 

package/template/.aioson/design-docs/folder-structure.md

@@ -1,12 +1,17 @@
 ---
-description: "Universal folder organization rules — hierarchy, depth, naming, grouping"
-scope: "governance"
-agents: []
----
+description: "Universal folder organization rules — hierarchy, depth, naming, grouping"
+scope: "governance"
+agents: [dev, deyvin, architect]
+modes: [planning, executing]
+task_types: [implementation-architecture, file-creation, module-boundary, refactor]
+load_tier: trigger
+triggers: [creating files, moving files, splitting modules, designing implementation structure, folder structure]
+paths: [src/**, app/**, lib/**, template/**, tests/**]
+---
 
 # Folder Structure — Governance Rules
 
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+> Loaded by the context selector when implementation structure, file creation, moves, or module boundaries are in scope. Override per-project via `.aioson/rules/`.
 
 ## Depth
 

package/template/.aioson/design-docs/naming.md

@@ -1,12 +1,17 @@
 ---
-description: "Naming conventions for files, variables, functions, and classes"
-scope: "governance"
-agents: []
----
+description: "Naming conventions for files, variables, functions, and classes"
+scope: "governance"
+agents: [dev, deyvin, architect]
+modes: [planning, executing]
+task_types: [implementation-architecture, file-creation, naming, refactor]
+load_tier: trigger
+triggers: [naming files, naming APIs, creating files, adding functions, adding classes, choosing names]
+paths: [src/**, app/**, lib/**, template/**, tests/**]
+---
 
 # Naming — Governance Rules
 
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+> Loaded by the context selector when naming files, APIs, functions, classes, or implementation paths is in scope. Override per-project via `.aioson/rules/`.
 
 ## Files
 

package/template/.aioson/docs/autonomy-protocol.md

@@ -14,8 +14,8 @@ Visual notifier: `aioson notify --level=info|warn|block`.
 
 | Tier | Intent | UX | Examples |
 |---|---|---|---|
-| `tier1_silent`   | Read-only and telemetry. Auto-execute, no notification.                | none           | `git status`, `aioson preflight`, `aioson context:health`, `agent:done` |
-| `tier2_notified` | Mutates AIOSON memory (`bootstrap/`, `features/`, `runtime/`). Auto-execute with **inline notify** (ℹ).         | `ℹ [topic] msg` | `memory:reflect-prepare`, `memory:reflect-commit`, `workflow:next`, `dossier:*` |
+| `tier1_silent`   | Read-only and telemetry. Auto-execute, no notification.                | none           | `git status`, `aioson preflight`, `aioson context:health`, `agent:done`, `review-cycle:status` |
+| `tier2_notified` | Mutates AIOSON memory (`bootstrap/`, `features/`, `runtime/`). Auto-execute with **inline notify** (ℹ).         | `ℹ [topic] msg` | `memory:reflect-prepare`, `memory:reflect-commit`, `workflow:next`, `dossier:*`, `agent:epilogue`, `review-cycle:advance|resolve|reset` |
 | `tier3_blocking` | Irreversible or external (publish, push, npm registry). **Never** auto-executed; the CLI returns exit 2 and waits for a human. | `⛔ [topic] msg` | `git push *`, `npm publish *`, `cloud:publish:*`, `genome:publish` |
 
 A tool opts into tiers via `derived_from_tiers`:

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

@@ -1,11 +1,14 @@
----
-description: "Autopilot handoff protocol: automatic agent chaining from @analyst to the @dev handoff in the feature workflow, with deterministic routing and explicit stop conditions"
----
-
-# Autopilot handoff (analyst → dev)
-
-Opt-in protocol that removes manual handoff confirmations in the deterministic segment of the feature workflow. Participating agents: `@analyst`, `@scope-check`, `@architect`, `@discovery-design-doc`, and `@pm` (MEDIUM features only — it sits between `@discovery-design-doc` and pre-dev `@scope-check` to produce the implementation plan and close Gate C). Upstream agents (`@briefing`, `@product`, `@sheldon`) always stay manual — they end on genuine human decisions.
-
+---
+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."
+---
+
+# Autopilot handoff (analyst → 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.
+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
 
 Autopilot is active only when ALL are true:
@@ -14,33 +17,78 @@ Autopilot is active only when ALL are true:
 2. A feature workflow is active (feature slug known, classification SMALL or MEDIUM).
 3. The current agent's own gate/verdict passed (see stop conditions).
 
-## Routing — deterministic, never LLM-chosen
-
-The next agent comes from the workflow state machine, not from model judgment:
-
-- CLI available: run `aioson workflow:next .` (inspect mode) and use the stage it reports, or the `next` field of `.aioson/context/workflow.state.json`.
-- CLI absent: follow the classification sequence in `.aioson/config.md` exactly.
-
-Never skip a stage, reorder, or pick an agent the state machine did not name.
-
+Preferred runtime entrypoint:
+
+```bash
+aioson workflow:execute . --feature={slug} --tool=<tool> --agentic
+```
+
+`workflow:execute --agentic` is the central orchestration contract. It writes `.aioson/context/workflow-execute.json` with `agentic_policy`, including the review-loop caps, sidecar/scout policy, lane guard, current checkpoint, and resumable command. Prompt-level `Skill(aioson:agent:<next>)` chaining remains a compatibility fallback for clients that cannot let the gateway consume this checkpoint.
+
+## Routing — deterministic, never LLM-chosen
+
+The next agent comes from the workflow state machine and on-disk evidence, not from model judgment:
+
+- CLI available: run `aioson workflow:next .` (inspect mode) and use the stage it reports, or the `next` field of `.aioson/context/workflow.state.json`.
+- CLI absent: follow the classification sequence in `.aioson/config.md` and the routing table below exactly.
+
+Never skip a stage, reorder, or pick an agent the state machine / routing table did not name.
+
 ## Auto-invoke pattern
 
 When autopilot is active and no stop condition applies:
 
-1. Finish your own closing duties first (artifacts on disk, gate registration, `pulse:update`, `agent:done`).
-2. Emit a one-line transition notice: `Autopilot: @<current> done → invoking @<next> (Ctrl+C to interrupt)`.
-3. Invoke `Skill(aioson:agent:<next>)` with the task `"continue feature {slug} — autopilot handoff from @<current>"`. No user prompt — Ctrl+C interrupts.
-
-## Stop conditions — break the chain and emit the normal manual handoff
-
-1. **Next agent is `@dev`** — goal reached. Produce `dev-state.md` (dev handoff producer), emit the standard handoff message, and recommend `/clear` + a fresh chat for `@dev`. Never auto-invoke `@dev`.
-2. **Verdict not clean** — `@scope-check` status is anything other than `approved`/`patched` (`needs-*`, `blocked`): route per Handoff Rules, manually.
-3. **Gate or readiness blocked** — `@architect` Gate B blocked, `@discovery-design-doc` readiness = `blocked`, or `@pm` Gate C blocked: stop and route to the owner.
-4. **Context budget** — estimated context usage ≥ `context_warning_threshold` (`.aioson/config.md`): write the compaction checkpoint to `.aioson/context/last-handoff.json`, stop, and recommend `/clear`. The workflow resumes from `workflow.state.json` — the next session re-enters autopilot automatically.
-5. **Ambiguity** — workflow state unavailable AND classification/sequence 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 (pre-analyst and at @dev); every autonomous loop needs explicit exit conditions; per-hop context checkpointing is the load-bearing cost mitigation.
+1. Finish your own closing duties first (artifacts on disk, gate registration, dossier/spec updates, `agent:epilogue`; `agent:done` remains the fallback).
+2. If the runtime checkpoint contains `agentic_policy.enabled=true`, let the gateway continue from `.aioson/context/workflow-execute.json`; do not ask the user to confirm the next deterministic stage.
+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`)
+
+SMALL feature: `@analyst` → `@scope-check` → `@architect` → `@discovery-design-doc` → `@dev`.
+
+MEDIUM feature: `@analyst` → `@architect` → `@discovery-design-doc` → `@pm` → `@scope-check` → `@dev`.
+
+The prompt-only fallback still stops before the FIRST `@dev` activation because `@dev` is a heavy phase and benefits from a fresh context window. Runtime agentic mode may cross this boundary only by starting a fresh `@dev` activation from the checkpoint/context package, not by carrying the upstream chat context forward. If the gateway cannot start that fresh activation, stop with the normal `/clear` + `/dev` recommendation.
+
+## Segment 2 — post-dev review cycle (hub = `@qa`)
+
+Once a human starts `@dev` and it finishes, the chain resumes automatically. `@qa` is the hub; every specialized agent returns to it.
+
+Routing table (each row is followed only when autopilot is active and no stop condition applies):
+
+| Current | Condition | Auto-invoke |
+|---|---|---|
+| `@dev` (first pass) | tests green, gates clear, no open corrections cycle | `@qa` |
+| `@dev` (corrections) | corrections applied, tests green (`review-cycle:status` active; `qa-dev-cycle.json` is legacy QA compatibility) | `@qa` (re-verify) |
+| `@qa` | verdict **FAIL** (Critical/High) | `@dev` via the corrections auto-cycle (cap 3, security gate) |
+| `@qa` | verdict **PASS** + `@tester` trigger fires AND `@tester` not yet run clean | `@tester` |
+| `@qa` | verdict **PASS** + `@pentester` trigger fires AND `@pentester` not yet run clean | `@pentester` |
+| `@qa` | verdict **PASS** + harness contract present AND `@validator` not yet PASS | `@validator` |
+| `@qa` | verdict **PASS** + no pending trigger/contract | **STOP** — recommend the human run `aioson feature:close . --feature={slug}` |
+| `@tester` | surfaced dev-owned blocking gaps | `@dev` |
+| `@tester` | no dev-owned blocking gaps | `@qa` (re-evaluate / sign-off) |
+| `@pentester` | open `recommended_owner = dev` findings | `@dev` |
+| `@pentester` | no open dev-owned findings | `@qa` (re-evaluate / sign-off) |
+| `@validator` | PASS | **STOP** — recommend the human run `aioson feature:close` |
+| `@validator` | FAIL | `@dev` |
+
+**Trigger source for `@tester`/`@pentester`:** the existing `@qa` trigger logic (coverage gaps → `@tester`; sensitive surface auth/secrets/data/upload/external-URL/supply-chain → `@pentester`). The four agents are ALWAYS wired into the chain, but `@tester`/`@pentester` only EXECUTE when their trigger fires — otherwise `@qa` skips straight to the next routing row.
+
+**Re-entry guard (no infinite loops):** before auto-invoking a specialized agent, `@qa` checks on-disk evidence that it already ran clean this cycle (e.g. `security-findings-{slug}.json` clean → `@pentester` done; a tester coverage artifact present with no new gap → `@tester` done; `progress.json.ready_for_done_gate` / validator PASS recorded → `@validator` done). An agent that already returned clean is not re-invoked.
+
+## Stop conditions — break the chain and emit the normal manual handoff
+
+1. **`feature:close` / publish** — ALWAYS the human gate. When `@qa` (PASS, nothing pending) or `@validator` (PASS) is the last clean step, STOP and recommend `aioson feature:close . --feature={slug}`. Never auto-run `feature:close`, `feature:archive`, `npm publish`, or any publish/close action.
+2. **First `@dev` entry without runtime gateway** — prompt-only clients stop here (Segment 1). Runtime agentic mode may continue only through a fresh checkpointed `@dev` activation.
+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 `/clear`. The workflow resumes from `workflow.state.json` — the next session re-enters autopilot automatically.
+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: fresh context) 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/briefing/briefing-craft.md

@@ -1,6 +1,12 @@
----
-description: "Oracle deep guide — strong vs weak briefing examples, JTBD problem framing, Opportunity Solution Tree, Cagan's four risks, gap analysis, open-questions taxonomy, conversation playbook. Load when an existing briefing feels weak, when the conversation goes generic, or when a complex Themes section needs partitioning."
----
+---
+description: "Oracle deep guide — strong vs weak briefing examples, JTBD problem framing, Opportunity Solution Tree, Cagan's four risks, gap analysis, open-questions taxonomy, conversation playbook. Load when an existing briefing feels weak, when the conversation goes generic, or when a complex Themes section needs partitioning."
+agents: [briefing]
+modes: [planning, executing]
+task_types: [briefing-craft, jtbd-framing, opportunity-mapping, gap-classification, briefing-quality]
+load_tier: justified
+triggers: [weak briefing, generic conversation, JTBD, opportunity solution tree, four risks, more than 3 open questions, complex themes, switch interview]
+tags: [briefing, jtbd, gaps, risks]
+---
 
 # Oracle — Briefing Craft