@jaimevalasek/aioson 1.23.0 → 1.23.3

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/tester.md

@@ -660,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
@@ -670,12 +670,18 @@ 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:done` is registered, return to the hub instead of stopping (`.aioson/docs/autopilot-handoff.md`):
+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"`.
 

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,12 +100,12 @@ 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:done` (`.aioson/docs/autopilot-handoff.md`):
+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.
 

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

@@ -9,13 +9,21 @@ Opt-in protocol that removes manual handoff confirmations in the deterministic s
 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:
-
-1. `project.context.md` frontmatter has `auto_handoff: true` (absent or `false` = manual handoffs, current behavior).
-2. A feature workflow is active (feature slug known, classification SMALL or MEDIUM).
-3. The current agent's own gate/verdict passed (see stop conditions).
+## Activation
+
+Autopilot is active only when ALL are true:
+
+1. `project.context.md` frontmatter has `auto_handoff: true` (absent or `false` = manual handoffs, current behavior).
+2. A feature workflow is active (feature slug known, classification SMALL or MEDIUM).
+3. The current agent's own gate/verdict passed (see stop conditions).
+
+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
 
@@ -26,19 +34,22 @@ The next agent comes from the workflow state machine and on-disk evidence, not f
 
 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, dossier/spec updates, `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.
+## Auto-invoke pattern
+
+When autopilot is active and no stop condition applies:
+
+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`)
 
-`@analyst` → `@scope-check` → `@architect` → `@discovery-design-doc` → (`@pm` on MEDIUM) → **STOP before `@dev`**.
-
-The pre-dev chain stops before the FIRST `@dev` activation. The human clears context (`/clear`) and starts implementation with a fresh budget — `@dev` is a heavy phase and benefits from a clean context window. Produce `dev-state.md` (the dev handoff producer), emit the standard handoff message, and recommend `/clear` + `/dev`. **Never auto-invoke the initial `@dev` entry.**
+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`)
 
@@ -49,8 +60,8 @@ Routing table (each row is followed only when autopilot is active and no stop co
 | Current | Condition | Auto-invoke |
 |---|---|---|
 | `@dev` (first pass) | tests green, gates clear, no open corrections cycle | `@qa` |
-| `@dev` (corrections) | corrections applied, tests green (`qa-dev-cycle.json` present) | `@qa` (re-verify) |
-| `@qa` | verdict **FAIL** (Critical/High) | `@dev` via the corrections auto-cycle (cap 2, security gate) |
+| `@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` |
@@ -69,8 +80,8 @@ Routing table (each row is followed only when autopilot is active and no stop co
 ## Stop conditions — break the chain and emit the normal manual handoff
 
 1. **`feature:close` / publish** — ALWAYS the human gate. When `@qa` (PASS, nothing pending) or `@validator` (PASS) is the last clean step, STOP and recommend `aioson feature:close . --feature={slug}`. Never auto-run `feature:close`, `feature:archive`, `npm publish`, or any publish/close action.
-2. **First `@dev` entry** — the pre-dev chain stops here (Segment 1). The human clears context and starts implementation.
-3. **Corrections cap reached** — the `@qa`↔`@dev` auto-cycle is bounded at 2 rounds (`qa-dev-cycle.json`); when exhausted, stop and escalate to the human.
+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.

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
 

package/template/.aioson/docs/deyvin/continuity-recovery.md

@@ -4,25 +4,21 @@ description: "Deyvin continuity recovery — session start order, resumption rul
 
 # Deyvin Continuity Recovery
 
-Load this module at the start of every `@deyvin` session before touching code.
+Load this module only when the task is continuity recovery, recent-work reconstruction, stale-state diagnosis, or resuming an existing slice.
 
 ## Session start order
 
-Build context in this order:
-
-1. If `aioson` is available, run `aioson memory:summary . --last=5` as the fast continuity bootstrap
-2. Read `.aioson/context/project.context.md`
-3. Check `.aioson/rules/`; load universal rules and rules targeted at `deyvin`
-4. Check `.aioson/docs/`; load docs referenced by rules or relevant to the task
-5. If the task is specific, run `aioson context:pack . --agent=deyvin --goal="<task>"` and read the generated pack
-6. Read `.aioson/context/memory-index.md` if present
-7. Read `.aioson/context/spec-current.md` and `.aioson/context/spec-history.md` if present
-8. Read `.aioson/context/spec.md` if present
-9. Read `.aioson/context/features.md` if present; if a feature is in progress, also read `prd-{slug}.md`, `requirements-{slug}.md`, and `spec-{slug}.md`
-10. Read `.aioson/context/skeleton-system.md`, `discovery.md`, and `architecture.md` as needed
-11. When the task matches procedural tags, run `aioson brain:query . --tags=<tags> --min-quality=4`
-12. Inspect recent runtime state in `.aioson/runtime/aios.sqlite` when memory summary is insufficient
-13. Use Git only as a fallback after memory + runtime + rules/docs
+Build context in this order:
+
+1. If `aioson` is available, run `aioson memory:summary . --last=5` as the fast continuity bootstrap.
+2. Read `.aioson/context/project.context.md`
+3. Run `aioson context:select . --agent=deyvin --mode=planning --task="<task>" --paths="<known paths>"`.
+4. Load only the selected PLANNING files. Do not load full `.aioson/rules/`, `.aioson/docs/`, `.aioson/design-docs/`, `discovery.md`, or `architecture.md` from this step alone.
+5. If a feature slug is known, load its dossier/spec only when `context:select`, `dev-state.md`, or `project-pulse.md` points to that slug; use `spec-current.md` for active spec and `spec-history.md` only for history.
+6. If code inspection/editing is about to start, run `aioson context:select . --agent=deyvin --mode=executing --task="<task>" --paths="<files to touch>"` and load only the selected EXECUTING files.
+7. When the task matches procedural tags, run `aioson brain:query . --tags=<tags> --min-quality=4`.
+8. Inspect recent runtime state in `.aioson/runtime/aios.sqlite` when memory summary is insufficient.
+9. Use Git only as a fallback after memory + runtime + selected rules/docs.
 
 If the user asks what happened recently, answer from memory and runtime first. Go to Git only if those sources are insufficient.
 
@@ -39,12 +35,12 @@ Do not duplicate or rewrite the shared SDD references inside `@deyvin`.
 
 ## Brownfield guardrails
 
-If `framework_installed=true` in `project.context.md` and the task depends on existing system behavior:
-
-- prefer `discovery.md` + `spec.md` as the primary memory pair
-- use `skeleton-system.md` or `memory-index.md` first for faster orientation
-- if `discovery.md` is missing but scan artifacts exist, stop and hand off to `@analyst`
-- if broad architecture decisions are required, hand off to `@architect`
+If `framework_installed=true` in `project.context.md` and the task depends on existing system behavior:
+
+- prefer selected module memory, `memory-index.md`, dossier, or spec before opening broad `discovery.md` / `architecture.md`
+- use `skeleton-system.md` or `memory-index.md` first for faster orientation
+- if `discovery.md` is missing but scan artifacts exist, stop and hand off to `@analyst`
+- if broad architecture decisions are required, hand off to `@architect`
 
 ## Git fallback
 

package/template/.aioson/docs/product/conversation-playbook.md

@@ -1,6 +1,11 @@
----
-description: "Product conversation playbook — opening messages, batching rules, proactive triggers, conversation phases, and finalize/surprise handling."
----
+---
+description: "Product conversation playbook — opening messages, batching rules, proactive triggers, conversation phases, and finalize/surprise handling."
+agents: [product]
+modes: [planning]
+task_types: [product-conversation, product-intake, feature-definition, prd-scoping]
+load_tier: trigger
+triggers: [asking product questions, structured intake, broad product discovery, visual preferences, finalize conversation]
+---
 
 # Product Conversation Playbook
 

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

@@ -1,6 +1,11 @@
----
-description: "Product PRD contract — exact PRD structure, visual identity block, output paths, and next-step routing."
----
+---
+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