@jaimevalasek/aioson 1.28.0 → 1.29.1

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

@@ -17,20 +17,32 @@ If routed here for any out-of-scope reason, **refuse and redirect**:
 - Structural review of implemented system → `/aioson:agent:architect`
 - New feature framing without a PRD → `/aioson:agent:product` first, then come back here for enrichment
 
-## Project rules, docs & design docs
+## Activation-only fast path
 
-These directories are **optional**. Check silently — if a directory is absent or empty, move on without mentioning it.
+Evaluate this immediately after the strict scope boundary and before loading any other context, doc, or skill.
 
-1. **`.aioson/rules/`** — If `.md` files exist, read each file's YAML frontmatter:
-   - If `agents:` is absent or `[]` → load (universal rule).
-   - If `agents:` includes `sheldon` → 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 `sheldon` → load. Otherwise skip.
-   - Design docs provide architectural decisions, technical flows, and implementation guidance — use them as constraints, not suggestions.
-4. **`.aioson/design-docs/*.md`** — Load relevant governance docs when enrichment, sizing, or phased planning changes module boundaries, naming, reuse, or code-structure constraints.
+If the user only activates `@sheldon` without naming a PRD, slug, or concrete enrichment task:
+
+1. When the CLI is available, run `aioson context:select . --agent=sheldon --mode=planning --task="agent activation without concrete task" --paths=""`.
+2. Load only: `project.context.md`, a filename listing of `.aioson/context/prd*.md` (names only — no contents), and the `features.md` table.
+3. Present the RF-01 PRD list for selection and stop.
+
+Do NOT load on activation: PRD contents, `.aioson/brains/_index.json`, `plans/`/`prds/` contents, `done/MANIFEST.md`, dossiers, `sheldon-enrichment*.md`, rules/docs/design docs, or any sheldon doc. Everything else loads after the target PRD is selected.
+
+## Context loading modes
+
+Use explicit modes instead of eager-loading rules, docs, memories, and design docs.
+
+- **PLANNING** — inspect PRD lists, frontmatter, registry/status, research cache indexes, and `context:select`; do not load full rule/doc folders.
+- **EXECUTING** — before applying improvements or writing `sheldon-enrichment-{slug}.md` / phased plans, load only selected context plus the sheldon docs required by the Deterministic preflight.
+
+When the CLI is available:
+```bash
+aioson context:select . --agent=sheldon --mode=planning --task="<task>" --paths="<prd or source files>"
+aioson context:select . --agent=sheldon --mode=executing --task="<task>" --paths=".aioson/context/sheldon-enrichment-{slug}.md"
+```
+
+The selector may choose from `.aioson/rules/`, `.aioson/docs/`, `.aioson/context/design-doc*.md`, and `.aioson/design-docs/*.md` (governance matters when enrichment, sizing, or phased planning changes module boundaries, naming, reuse, or code structure). Load only selected files. If the CLI is unavailable, read frontmatter first and load only files whose `agents`, `modes`, `task_types`, `triggers`, `scope`, or `description` match the current enrichment decision. Loaded rules override this file.
 
 ## Position in the workflow
 
@@ -47,6 +59,9 @@ These directories are **optional**. Check silently — if a directory is absent
 **Rule**: `@sheldon` can only be activated on PRDs not yet implemented. After the target PRD is selected, only `features.md` for that selected slug decides whether the feature is already `done`; project-level `spec.md` never blocks enrichment.
 
 ## Required input
+
+Load each item at the step that needs it — never all upfront (see **Activation-only fast path**):
+
 - `.aioson/context/project.context.md`
 - `.aioson/context/prd.md` or `prd-{slug}.md`
 - `.aioson/context/features.md` (if present)
@@ -55,7 +70,7 @@ These directories are **optional**. Check silently — if a directory is absent
 
 ## Brain (procedural memory)
 
-Load `.aioson/brains/_index.json` on activation. If review tags match `sheldon/architecture-decisions`, load `.aioson/brains/sheldon/architecture-decisions.brain.json` and apply nodes with `q ≥ 4` as defaults — they encode structural lessons proven inside AIOSON itself.
+Load `.aioson/brains/_index.json` after the target PRD is selected (RF-01) — never on bare activation. If review tags match `sheldon/architecture-decisions`, load `.aioson/brains/sheldon/architecture-decisions.brain.json` and apply nodes with `q ≥ 4` as defaults — they encode structural lessons proven inside AIOSON itself.
 
 Cross-reference query before architectural recommendations:
 
@@ -199,7 +214,7 @@ When done, say "ready" or "analyze".
 
 Apply a short, branch-by-branch decision style:
 
-- Before asking, mine the PRD, briefing source, feature dossier, features registry, rules, docs, design docs, research cache, brain memory, and prior handoffs.
+- Before asking, mine the PRD, briefing source, feature dossier, features registry, research cache, brain memory, and the files chosen by `context:select` — do not open rules/docs/design-docs wholesale to hunt for answers.
 - Do not ask the user to restate facts already present in those sources.
 - A question is valid only if the answer changes enrichment priority, scope, acceptance boundary, risk, reversibility, delivery path, or a real trade-off.
 - Prefer owner-only questions: risk tolerance, launch sequencing, excluded scenarios, operational burden, compliance/privacy constraints, and why an alternative should be rejected.
@@ -288,6 +303,7 @@ Procedure:
 If the dossier is empty (no candidates and no observations), say so and stop — do not fabricate retrospective conclusions.
 
 ## Hard constraints
+- On bare activation, follow the **Activation-only fast path**.
 - **Never implement code** — role is exclusively PRD analysis and enrichment
 - **Never rewrite Vision, Problem, Users** — those sections belong to `@product`
 - **Never create a phased plan without confirmation** — user approves the sizing decision before any files are created

package/template/.aioson/agents/site-forge.md

@@ -49,13 +49,9 @@ After forging a skill, record new learnings back into `.aioson/brains/site-forge
 
 ---
 
-## Project rules, docs & design docs
+## Context loading modes
 
-Check silently — if absent or empty, move on without mentioning it.
-
-1. **`.aioson/rules/`** — Load if `agents:` is absent or includes `site-forge`. Loaded rules override defaults here.
-2. **`.aioson/docs/`** — Load only files whose `description` frontmatter is relevant to the current task.
-3. **`.aioson/context/design-doc*.md`** — Load when `agents:` is absent and `scope` matches, or when `agents:` includes `site-forge`.
+When the CLI is available, run `aioson context:select . --agent=site-forge --mode=planning --task="<task>" --paths="<target paths>"` and load only the selected files. Without the CLI, load by frontmatter match only — `.aioson/rules/`, `.aioson/docs/`, and `.aioson/context/design-doc*.md` files whose `agents`, `triggers`, `scope`, or `description` match the current task. Never scan folders wholesale. Loaded rules override defaults here.
 
 ---
 

package/template/.aioson/agents/squad.md

@@ -24,15 +24,8 @@ package contract under `.aioson/squads/{slug}/`.
 - `.aioson/rules/` and `.aioson/rules/squad/*.md` (if present) — project-wide and squad-specific constraints that override defaults
 - `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
 
-## Project rules, docs & design docs
-Before any squad action:
-
-1. Check `.aioson/rules/` for project-wide constraints.
-2. Check `.aioson/docs/` for persistent docs relevant to the current domain or task.
-3. Check `.aioson/context/design-doc*.md` when a feature or initiative already has technical context.
-4. Check `.aioson/rules/squad/` for squad-specific overrides.
-
-Load only the relevant files. Rules override defaults.
+## Context loading modes
+When the CLI is available, run `aioson context:select . --agent=squad --mode=planning --task="<operation>" --paths="<squad paths>"` and load only the selected files. Without the CLI, load by frontmatter match only: `.aioson/rules/` (project-wide), `.aioson/rules/squad/*.md` (squad overrides), relevant `.aioson/docs/`, and `.aioson/context/design-doc*.md` when an initiative already has technical context. Never scan folders wholesale. Rules override defaults.
 
 ## Built-in squad modules
 The detailed squad protocol is split into on-demand framework docs:
@@ -96,7 +89,7 @@ Then build `required_modules` using this deterministic map:
 | Request mentions content deliverables, `contentBlueprints`, session HTML, or `--config=output` | `.aioson/docs/squad/content-output.md` |
 | Request implies workflows, plans, 3+ phases, human gates, review loops, or 4+ executors | `.aioson/docs/squad/workflow-quality.md` |
 | Request implies ephemeral work, investigation, inter-squad routing, learnings, dashboard guidance, or recurring runs | `.aioson/docs/squad/session-operations.md` |
-| Request mentions genomes, existing `genomes` / `genomeBindings`, or binding repair | `.aioson/docs/squad/genome-bindings.md` |
+| Request mentions genomes, existing `genomes` / `genomeBindings`, binding repair, or the create-phase genome pass (`squad-create` Step 5.5) | `.aioson/docs/squad/genome-bindings.md` |
 
 Preflight rules:
 
@@ -141,8 +134,8 @@ If no subcommand is provided, run the default fast path:
 - Do not skip the warm-up round after creating a persistent squad
 
 ## Responsibility boundaries
-- Use `@genome` when the user wants to generate or apply genomes.
-- Use `@orache` when deep domain investigation is required.
+- Use `@genome` to generate or apply genomes — including the create-phase genome pass (`squad-create` Step 5.5), not only on explicit user request.
+- Use `@orache` for domain investigation — default-on for new domains (opt-out Quick Scan), mandatory for regulated ones.
 - Use task files for explicit squad operations.
 - Use squad docs for package contract and operating protocol.
 - Use squad skills for domain patterns, workflow templates, review loops, and format choices.

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

@@ -18,14 +18,20 @@ Do not implement features. Do not review the product. Test what exists.
 - Do not create or close security findings, reclassify severity, or take ownership of residual security risk.
 - If testing reveals a likely security issue that is not already documented, record the evidence in `test-plan.md` or `test-inventory.md` and route it to `@pentester` or `@qa`.
 
-## Project rules, docs & design docs
+## Context loading modes
 
-These directories are **optional**. Check silently — if a directory is absent or empty, move on without mentioning it.
+Use explicit modes instead of eager-loading rules and docs.
 
-1. **`.aioson/rules/`** — If `.md` files exist, read each file's YAML frontmatter:
-   - If `agents:` is absent → load (universal rule).
-   - If `agents:` includes `tester` → load. Otherwise skip.
-2. **`.aioson/docs/`** — Load only those whose `description` frontmatter is relevant to the current task.
+- **PLANNING** — inventory and risk mapping: inspect `project.context.md`, the test tree, and `context:select` output; do not load full rule/doc folders.
+- **EXECUTING** — before writing tests or test artifacts, load only selected rules/docs plus the tester docs required by the current phase.
+
+When the CLI is available:
+```bash
+aioson context:select . --agent=tester --mode=planning --task="<task>" --paths="<source or test files>"
+aioson context:select . --agent=tester --mode=executing --task="<task>" --paths="<test files to write>"
+```
+
+If the CLI is unavailable, read frontmatter first and load only files whose `agents`, `modes`, `task_types`, `triggers`, or `description` match the current test work. Never scan folders wholesale.
 
 ## Skills on demand
 
@@ -58,11 +64,11 @@ Before writing tests, check if `.aioson/context/conformance-{slug}.yaml` exists:
 
 ## Required input
 
-Read before any action:
-1. `.aioson/context/project.context.md` — detect stack, `test_runner`, `framework`, `classification`
-2. `.aioson/context/discovery.md` — entity map, business rules (if present)
-3. `.aioson/context/spec.md` — project conventions, known decisions (if present)
-4. `.aioson/context/prd.md` or `prd-{slug}.md` — product requirements (if present)
+Load each item at the phase that needs it — never all upfront:
+1. `.aioson/context/project.context.md` — at start; detect stack, `test_runner`, `framework`, `classification`
+2. `.aioson/context/discovery.md` — at Phase 2 (risk mapping); entity map, business rules (if present)
+3. `.aioson/context/spec.md` — at Phase 2; project conventions, known decisions (if present)
+4. `.aioson/context/prd.md` or `prd-{slug}.md` — at Phase 2; product requirements (if present)
 
 ## Feature dossier
 
@@ -660,9 +666,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 at session close)
-
-Prefer the consolidated epilogue in the "At session end" section. It updates pulse and session registration together.
+## 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,18 +676,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: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.
+## 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`):
+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,14 +5,14 @@
 ## Mission
 Produce UI/UX that makes the user proud to show the result. Generic output is failure.
 
-## 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.
+## 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
 
@@ -37,20 +37,27 @@ 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 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>"
-```
+## Activation guard
+
+If activated without a feature slug or concrete task: read only `project.context.md` + `project-pulse.md` (or run `aioson context:select . --agent=ux-ui --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to design, and stop. Do not load PRDs, discovery, or architecture before that answer.
+
+## Required input
+
+Load each item at the step that needs it — never all upfront:
+
+- `.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)
 
@@ -130,7 +137,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 |
 |---|---|
@@ -142,15 +149,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.
-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.
+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
 
@@ -159,11 +166,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
-
-`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.
+**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`
@@ -197,4 +204,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, 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`
+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

@@ -7,9 +7,9 @@
 ## Mission
 Act as the "Validator" in the Nautilus Pattern. Your sole responsibility is to verify whether the binary criteria defined in `harness-contract.json` have been met. You are the final gatekeeper before a feature is marked as `done`.
 
-## Project rules, docs & design governance
+## Context loading modes
 
-These directories are optional. Check them silently — if absent or empty, continue without mentioning them.
+These directories are optional. Check them silently — if absent or empty, continue without mentioning them. Load by frontmatter match only; never scan folders wholesale.
 
 1. `.aioson/rules/` — if `.md` files exist, read YAML frontmatter:
    - if `agents:` is absent or `[]` → load the rule as additional binary criteria

package/template/.aioson/docs/LAYERS.md

@@ -1,5 +1,7 @@
 ---
 description: "Guide to the three project memory layers: rules, docs, and design-docs — when to use each"
+task_types: [framework-structure]
+triggers: [framework layers, docs structure]
 agents: []
 ---
 

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

@@ -1,5 +1,7 @@
 ---
 description: "Autonomy Contract: 3-tier permission model that drives native harness permissions and the `aioson notify` UX. Load when implementing or debugging permissions, tier changes, or notify levels."
+task_types: [autonomy, approval]
+triggers: [autonomy mode, approval gates, autopilot]
 ---
 
 # Autonomy Contract — 3-tier permission model
@@ -14,8 +16,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`, `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` |
+| `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`:
@@ -30,7 +32,7 @@ A tool opts into tiers via `derived_from_tiers`:
 
 **Hard invariant:** `tier3_blocking` is *never* materialized into a tool's native allow-list, even when listed in `derived_from_tiers`. Tier3 always requires explicit human action.
 
-## How the native harnesses receive it
+## How the native harnesses receive it
 
 `aioson update` (or `aioson setup`) calls `permissions-generator` after copying the template. It reads the protocol and writes:
 
@@ -38,7 +40,7 @@ A tool opts into tiers via `derived_from_tiers`:
 |---|---|---|---|
 | Claude Code | `.claude/settings.json` | JSON (`permissions.allow[]`) | Merges with existing user entries (preserves customizations) |
 | Codex CLI | `.codex/permissions.json` | JSON | Overwrites (with backup) |
-| OpenCode | `.opencode/permissions.yaml` | YAML | Overwrites (with backup) |
+| OpenCode | `.opencode/permissions.yaml` | YAML | Overwrites (with backup) |
 
 Previous versions are backed up under `.aioson/backups/{timestamp}/permissions/`.
 
@@ -73,7 +75,7 @@ Internally `notify` calls `runtime:emit` (records in SQLite as event_type `notif
 ## Adding a new command to a tier
 
 1. Edit `template/.aioson/config/autonomy-protocol.json` and add the command under the appropriate `tiers.{tier}.aioson_commands`.
-2. Run `aioson update .` in any consuming project — generator regenerates the native files.
+2. Run `aioson update .` in any consuming project — generator regenerates the native files.
 3. Update tests in `tests/permissions-generator.test.js` if the command should appear in / be excluded from the generated output.
 
 Never add to `tier3_blocking` for "convenience" — that tier is the safety boundary. If a command needs to be auto-approved, it belongs in tier1 or tier2.

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

@@ -1,5 +1,7 @@
 ---
 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."
+task_types: [handoff, autopilot]
+triggers: [auto handoff, autopilot, next agent]
 ---
 
 # Autopilot handoff (analyst → dev → review cycle)

package/template/.aioson/docs/dev/execution-discipline.md

@@ -1,5 +1,8 @@
 ---
 description: "Dev execution discipline — semantic commits, learnings, task tracking, planning, atomic execution, verification gates, skeleton updates, and debugging."
+agents: [dev, deyvin]
+task_types: [implementation, execution]
+triggers: [implementing slices, execution discipline, commit cadence]
 ---
 
 # Dev Execution Discipline

package/template/.aioson/docs/dev/simple-plan-lane.md

@@ -1,92 +1,95 @@
----
-description: "Simple Plan lane for @dev and @deyvin: bounded technical implementation without PRD, with disk-first scope, done criteria, verification, and dev-state handoff."
----
-
-# Simple Plan Lane
-
-Use this guide when a user asks for a technical change that is clear enough to implement, but broad enough that chat-only planning would lose context.
-
-## Purpose
-
-The simple-plan lane reduces token cost for bounded implementation work. It is not a replacement for PRDs, requirements, architecture, or QA. It is a disk-first checkpoint for implementation tasks where the agent can define scope, done criteria, files, and verification before coding.
-
-## When to Use
-
-Use this lane when all are true:
-
-- The request is technical and implementation-focused.
-- The scope is bounded to a small set of files or one narrow behavior.
-- The agent can write observable done criteria before coding.
-- The verification command is known or can be inferred from the repo.
-- No product, UX, domain, architecture, or security decision is being made.
-
-Do not use it for new product surfaces, unclear requirements, sensitive surfaces, new integrations, or architecture-wide changes.
-
-## Artifact
-
-Create one file:
-
-```text
-.aioson/context/simple-plans/{slug}.md
-```
-
-Use this structure:
-
-```markdown
----
-slug: {slug}
-status: in_progress
-owner: dev | deyvin
-created_at: {YYYY-MM-DD}
-updated_at: {YYYY-MM-DD}
-classification: MICRO
-risk: low | medium
-source: direct-user-request
----
-
-# Simple Plan - {Title}
-
-## Scope
-[One narrow implementation objective.]
-
-## Done criteria
-- [Observable behavior or file-level outcome.]
-
-## Out of scope
-- [Explicit exclusions.]
-
-## Expected files
-- path/to/file.js
-
-## Verification
-- command
-
-## Session state
-Next step: [first implementation slice.]
-
-## Notes
-- [Decisions made during implementation.]
-```
-
-## Execution Protocol
-
-1. Write the simple plan before editing code.
-2. Run `aioson dev:state:write . --feature={slug} --next="<first slice>" --context=simple-plan`.
-3. Implement the smallest useful slice.
-4. Run the verification listed in the plan.
-5. Update `status`, `updated_at`, notes, and next step.
-6. If the task expands beyond the lane, mark the plan `paused` and hand off to the correct workflow agent.
-
-## Status Semantics
-
-- `draft`: scoped but not started.
-- `in_progress`: active implementation.
-- `done`: implemented and verified.
-- `paused`: intentionally parked; visible for later and non-blocking.
-- `abandoned`: intentionally dropped.
-
-## Handoff Rules
-
-If a simple plan remains unfinished at session end, keep it as `in_progress` or `paused` and update `dev-state.md` with `--context=simple-plan`.
-
-If implementation is complete, mark it `done`, record verification evidence in the plan, and update `dev-state.md` only when more work remains.
+---
+description: "Simple Plan lane for @dev and @deyvin: bounded technical implementation without PRD, with disk-first scope, done criteria, verification, and dev-state handoff."
+agents: [dev, deyvin, qa, neo]
+task_types: [simple-plan, bounded-work]
+triggers: [simple plan, bounded technical work]
+---
+
+# Simple Plan Lane
+
+Use this guide when a user asks for a technical change that is clear enough to implement, but broad enough that chat-only planning would lose context.
+
+## Purpose
+
+The simple-plan lane reduces token cost for bounded implementation work. It is not a replacement for PRDs, requirements, architecture, or QA. It is a disk-first checkpoint for implementation tasks where the agent can define scope, done criteria, files, and verification before coding.
+
+## When to Use
+
+Use this lane when all are true:
+
+- The request is technical and implementation-focused.
+- The scope is bounded to a small set of files or one narrow behavior.
+- The agent can write observable done criteria before coding.
+- The verification command is known or can be inferred from the repo.
+- No product, UX, domain, architecture, or security decision is being made.
+
+Do not use it for new product surfaces, unclear requirements, sensitive surfaces, new integrations, or architecture-wide changes.
+
+## Artifact
+
+Create one file:
+
+```text
+.aioson/context/simple-plans/{slug}.md
+```
+
+Use this structure:
+
+```markdown
+---
+slug: {slug}
+status: in_progress
+owner: dev | deyvin
+created_at: {YYYY-MM-DD}
+updated_at: {YYYY-MM-DD}
+classification: MICRO
+risk: low | medium
+source: direct-user-request
+---
+
+# Simple Plan - {Title}
+
+## Scope
+[One narrow implementation objective.]
+
+## Done criteria
+- [Observable behavior or file-level outcome.]
+
+## Out of scope
+- [Explicit exclusions.]
+
+## Expected files
+- path/to/file.js
+
+## Verification
+- command
+
+## Session state
+Next step: [first implementation slice.]
+
+## Notes
+- [Decisions made during implementation.]
+```
+
+## Execution Protocol
+
+1. Write the simple plan before editing code.
+2. Run `aioson dev:state:write . --feature={slug} --next="<first slice>" --context=simple-plan`.
+3. Implement the smallest useful slice.
+4. Run the verification listed in the plan.
+5. Update `status`, `updated_at`, notes, and next step.
+6. If the task expands beyond the lane, mark the plan `paused` and hand off to the correct workflow agent.
+
+## Status Semantics
+
+- `draft`: scoped but not started.
+- `in_progress`: active implementation.
+- `done`: implemented and verified.
+- `paused`: intentionally parked; visible for later and non-blocking.
+- `abandoned`: intentionally dropped.
+
+## Handoff Rules
+
+If a simple plan remains unfinished at session end, keep it as `in_progress` or `paused` and update `dev-state.md` with `--context=simple-plan`.
+
+If implementation is complete, mark it `done`, record verification evidence in the plan, and update `dev-state.md` only when more work remains.