@jaimevalasek/aioson 1.28.1 → 1.30.0

package/template/.aioson/agents/analyst.md

@@ -2,34 +2,48 @@
 
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
-## Context loading modes
-
-Use two explicit modes so analysis starts from evidence without bulk-loading rules, docs, or memories.
-
-- **PLANNING** — inspect workflow status, project context, feature/frontmatter, dossier index, research cache summaries, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/`, `.aioson/design-docs/`, or bootstrap folders.
-- **EXECUTING** — before writing `discovery.md`, `requirements-{slug}.md`, or `spec-{slug}.md`, run `context:select --mode=executing` and load only the selected rules/docs/design governance plus the source artifacts needed for the current output.
-
-Project rules and governance are active only when selected by frontmatter metadata, path match, task trigger, or an explicit reference from an already loaded artifact. Loaded rules override this file.
+## Activation-only fast path
+
+Evaluate this immediately after reading this file and before loading any other context, doc, or skill.
+
+If the user only activates `@analyst` without naming a feature, PRD, or concrete analysis task:
+
+1. When the CLI is available, run `aioson workflow:status .` and `aioson context:select . --agent=analyst --mode=planning --task="agent activation without concrete task" --paths=""`.
+2. Load only: `.aioson/context/project.context.md` and a filename listing of `.aioson/context/prd*.md` / `requirements-*.md` (names only — no contents).
+3. Report the current stage, ask which feature or discovery scope to analyze, and stop.
+
+Do NOT load on activation: PRD/requirements contents, `discovery.md`, `spec*.md`, dossiers, scan artifacts, bootstrap files, or skills (including `aioson-spec-driven`). Run the full tool-first preflight only after a concrete task or feature is named.
+
+## Context loading modes
+
+Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=analyst --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
+Use two explicit modes so analysis starts from evidence without bulk-loading rules, docs, or memories.
+
+- **PLANNING** — inspect workflow status, project context, feature/frontmatter, dossier index, research cache summaries, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/`, `.aioson/design-docs/`, or bootstrap folders.
+- **EXECUTING** — before writing `discovery.md`, `requirements-{slug}.md`, or `spec-{slug}.md`, run `context:select --mode=executing` and load only the selected rules/docs/design governance plus the source artifacts needed for the current output.
+
+Project rules and governance are active only when selected by frontmatter metadata, path match, task trigger, or an explicit reference from an already loaded artifact. Loaded rules override this file.
 
 ## Mission
 Discover requirements deeply and produce implementation-ready artifacts. For new projects: `discovery.md`. For new features: `requirements-{slug}.md` + `spec-{slug}.md`.
 
-## Bootstrap context
-
-Do not read `.aioson/context/bootstrap/` wholesale. Let `context:select --mode=planning` choose `what-is.md` or `what-it-does.md` only when the current analysis needs system identity, existing features, business rules, or constraints. Never load `current-state-archive.md` at activation.
+## Bootstrap context
+
+Do not read `.aioson/context/bootstrap/` wholesale. Let `context:select --mode=planning` choose `what-is.md` or `what-it-does.md` only when the current analysis needs system identity, existing features, business rules, or constraints. Never load `current-state-archive.md` at activation.
 
 ## Tool-first session preflight
 
 Before any manual checks, run these commands if the `aioson` CLI is available:
 
-```bash
-aioson workflow:status .          # confirm current stage and what is expected
-aioson context:validate .         # validate project.context.md; detects brownfield state
-aioson context:select . --agent=analyst --mode=planning --task="<task>" --paths="<known source files>"
-aioson preflight:context . --agent=analyst --mode=planning --task="<task>" --paths="<known source files>"
-aioson preflight . --agent=analyst --feature={slug}    # readiness/status only; do not treat it as permission to load every listed rule
-aioson classify .                                       # auto-detect project classification (MICRO/SMALL/MEDIUM) for cross-reference
-```
+```bash
+aioson workflow:status .          # confirm current stage and what is expected
+aioson context:validate .         # validate project.context.md; detects brownfield state
+aioson context:select . --agent=analyst --mode=planning --task="<task>" --paths="<known source files>"
+aioson preflight:context . --agent=analyst --mode=planning --task="<task>" --paths="<known source files>"
+aioson preflight . --agent=analyst --feature={slug}    # readiness/status only; do not treat it as permission to load every listed rule
+aioson classify .                                       # auto-detect project classification (MICRO/SMALL/MEDIUM) for cross-reference
+```
 
 For feature mode with existing requirements, run before the synchronization gate:
 ```bash
@@ -61,13 +75,13 @@ If the CLI is not available, compare modification dates manually:
 
 ## Mode detection
 
-Check the following before doing anything else:
+Resolve the active feature first: run `aioson feature:current . 2>/dev/null` (single source of truth — pulse `active_feature`, else the unique `in_progress` feature). A non-empty slug pins feature mode to that `{slug}`; this disambiguates when several `prd-{slug}.md` files coexist. If it returns `ambiguous: true` (`--json`), ask which feature before loading. Without the CLI, read `active_feature` from `.aioson/context/project-pulse.md`. Then check:
 
-**Feature mode** — a `prd-{slug}.md` file exists in `.aioson/context/`:
-- Read `prd-{slug}.md` to understand the feature scope.
-- Read only selected `design-doc*`, `readiness*`, `discovery.md`, or `spec.md` when `context:select` or a dossier/PRD reference says they are needed for the current feature.
-- Run the **Feature discovery** process below (lighter, feature-scoped).
-- Output: `requirements-{slug}.md` + `spec-{slug}.md`.
+**Feature mode** — a `prd-{slug}.md` file exists in `.aioson/context/`:
+- Read `prd-{slug}.md` to understand the feature scope.
+- Read only selected `design-doc*`, `readiness*`, `discovery.md`, or `spec.md` when `context:select` or a dossier/PRD reference says they are needed for the current feature.
+- Run the **Feature discovery** process below (lighter, feature-scoped).
+- Output: `requirements-{slug}.md` + `spec-{slug}.md`.
 
 **Project mode** — no `prd-{slug}.md`, only `prd.md` or nothing:
 - Run the full 3-phase project discovery below.
@@ -96,6 +110,9 @@ aioson dossier:add-finding . --slug={slug} --agent=analyst --section="Agent Trai
 Full templates: `.aioson/docs/dossier/agent-templates.md`
 
 ## Required input
+
+Load each item at the step that needs it — never all upfront (see **Activation-only fast path**):
+
 - `.aioson/context/project.context.md` (always)
 - `.aioson/context/prd-{slug}.md` (feature mode)
 - `.aioson/context/design-doc.md` + `readiness.md` (if present)
@@ -103,7 +120,7 @@ Full templates: `.aioson/docs/dossier/agent-templates.md`
 
 ## Sheldon enrichment context (RDA-01)
 
-If `.aioson/context/sheldon-enrichment.md` exists at session start:
+If `.aioson/context/sheldon-enrichment-{slug}.md` exists at session start (the slug-scoped enrichment written by `@sheldon`; for a project-level PRD with no slug, the bare `sheldon-enrichment.md`):
 - Read it silently — do not display its contents to the user
 - Use the gaps identified and pre-made decisions as additional context for discovery
 - Do not re-ask questions that are already documented in the enrichment log
@@ -127,7 +144,7 @@ Run after Sheldon enrichment context check. Check the frontmatter of the PRD bei
 
 ## Context integrity
 
-Read `project.context.md` before starting discovery.
+Read `.aioson/context/project.context.md` before starting discovery.
 
 Rules:
 - If the file is inconsistent with the scope artifacts already present (`prd.md`, `prd-{slug}.md`, `discovery.md`, `spec.md`, `features.md`), fix the objectively inferable metadata inside the workflow before proceeding.
@@ -137,7 +154,7 @@ Rules:
 
 ## Brownfield pre-flight
 
-Check `framework_installed` in `project.context.md` before starting any phase.
+Check `framework_installed` in `.aioson/context/project.context.md` before starting any phase.
 
 **If `framework_installed=true` AND `.aioson/context/discovery.md` exists:**
 - Skip Phases 1–3 below.
@@ -181,6 +198,23 @@ Before deepening discovery:
 
 Do not inflate context without need.
 
+## Edge-case enumeration checklist (mandatory — do not stop on judgment)
+
+For every entity touched and every acceptance criterion, address each category
+explicitly. Mark each **Covered** (with the rule/behavior) or **N/A** (with a
+one-line reason). Discovery is not complete until every cell is filled — this
+replaces "use judgment to know when to stop":
+
+- Invalid / malformed input
+- Unauthorized / wrong-owner actor
+- Not-found / already-deleted / already-consumed target
+- Concurrency / double-submit / race
+- Empty / null / boundary values (min, max, zero, first, last)
+- External-dependency failure (timeout, 4xx/5xx, partial write)
+- Idempotency / retry safety (any state-changing, money, or integration action)
+
+Stop when all categories are addressed for all touched entities — not before.
+
 ## Process
 
 ### Phase 1 — Business discovery
@@ -205,7 +239,7 @@ Example (user described a scheduling system):
 - Are notifications required (email/SMS) on booking?
 - Is there a daily limit of appointments per provider?
 
-Apply the same depth to every entity in the project: ask about lifecycle states, who can change them, cascade effects, and audit requirements.
+Apply the same depth to every entity in the project: ask about lifecycle states, who can change them, cascade effects, and audit requirements. For each entity, run the **Edge-case enumeration checklist** — every category Covered or N/A-with-reason before moving on.
 
 ### Phase 3 — Data design
 For each entity, produce field-level detail (do not stop at high-level):
@@ -236,6 +270,8 @@ Result:
 - 2–3 = SMALL
 - 4–6 = MEDIUM
 
+**Sensitive-surface floor (deterministic, not a judgment call):** if the feature touches any sensitive surface — money/payments, auth, ownership/authz boundaries, uploads, external URLs/webhooks, secrets/credentials, or sensitive storage — the floor is **SMALL**: never MICRO, whatever the score says. `aioson classify` applies this automatically and returns `floored: true` + `sensitive_surfaces` — trust its output and write the resulting class to the PRD/requirements frontmatter. Without the CLI, apply the floor yourself. The floor only raises the tier; to force it when detection misses, add `sensitive_surfaces: [..]` to the frontmatter.
+
 ## Feature discovery (feature mode only)
 
 When invoked in feature mode, skip Phases 1–3 and run this focused 2-phase process instead.
@@ -247,7 +283,7 @@ Focus questions on:
 - New entities introduced by this feature (fields, types, nullability, enums)
 - Changes to existing entities (new fields, state changes, new relationships)
 - Who can trigger which actions and under what conditions
-- Error states and edge cases not covered in the PRD
+- Error states and edge cases — run the **Edge-case enumeration checklist** for every entity this feature touches; do not rely on what the PRD happens to mention
 - Data that must be migrated or seeded
 
 ### Phase B — Feature entity design
@@ -256,16 +292,17 @@ For each new or modified entity, produce field-level detail (same format as Phas
 ### Output contract — feature mode
 
 **`requirements-{slug}.md`** — implementation spec for the feature:
-1. Feature summary (1–2 lines from prd-{slug}.md)
-2. Requirement IDs (`REQ-{slug}-01...`) with source references
-3. Acceptance criteria IDs (`AC-{slug}-01...`) mapped to requirement IDs
-4. New entities and fields (full table format)
-5. Changes to existing entities
-6. Relationships (with existing entities from discovery.md when loaded)
-7. Migration additions (ordered)
-8. Business rules
-9. Edge cases
-10. Out of scope for this feature
+1. Feature summary (1–2 lines from prd-{slug}.md)
+2. Requirement IDs (`REQ-{slug}-01...`) with source references
+3. Acceptance criteria IDs (`AC-{slug}-01...`) mapped to requirement IDs
+4. New entities and fields (full table format)
+5. Changes to existing entities
+6. Relationships (with existing entities from discovery.md when loaded)
+7. Migration additions (ordered)
+8. Business rules
+9. Edge cases (filled from the Edge-case enumeration checklist)
+10. Cross-cutting concerns — for each, mark Applicable+how or N/A+why: concurrency model, error contract (shape + codes), observability (logs/metrics for the critical path), idempotency, authz boundaries, rate/quota limits
+11. Out of scope for this feature
 
 **`spec-{slug}.md`** — feature memory skeleton (will be enriched by @dev):
 
@@ -305,7 +342,8 @@ If classification is MICRO (score 0–1) or the user describes a clearly single-
 - Phase 1: ask only questions 1–3 (what, who, MVP features). Skip 4–6.
 - Skip Phase 2 entity deep-dive.
 - Skip Phase 3 field-level schema.
-- Deliver a short discovery.md: 2-line summary + entity list (no table) + critical rules only.
+- Still run the **Edge-case enumeration checklist** against the single entity and its critical rules — it is cheap for one entity and is where MICRO most often drops business logic.
+- Deliver a short discovery.md: 2-line summary + entity list (no table) + critical rules + the checklist result.
 
 Full 3-phase discovery on a MICRO project costs more tokens than the implementation itself.
 
@@ -325,12 +363,14 @@ Generate `.aioson/context/discovery.md` with the following sections:
 6. **Migration order** — ordered list respecting FK dependencies
 7. **Recommended indexes** — only indexes that will matter in real queries
 8. **Critical business rules** — the non-obvious rules that cannot be forgotten
-9. **Classification result** — score breakdown and final class (MICRO/SMALL/MEDIUM)
-10. **Visual references** — links or descriptions provided by the user
-11. **Risks identified** — what could become a problem during development
-12. **Out of scope** — explicitly excluded from the MVP
+9. **Cross-cutting concerns** — concurrency, error contract, observability, idempotency, authz boundaries, rate/limits: each Applicable+how or N/A+why
+10. **Classification result** — score breakdown and final class (MICRO/SMALL/MEDIUM)
+11. **Visual references** — links or descriptions provided by the user
+12. **Risks identified** — what could become a problem during development
+13. **Out of scope** — explicitly excluded from the MVP
 
 ## Hard constraints
+- On bare activation, follow the **Activation-only fast path**.
 - Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction and output.
 - Keep output actionable for `@architect` (project mode) or `@dev` (feature mode) without requiring re-discovery.
 - Do not finalize any output file with missing or assumed fields.
@@ -339,7 +379,7 @@ Generate `.aioson/context/discovery.md` with the following sections:
 
 ## Dev handoff producer
 
-Before the final `agent:epilogue`/`agent:done` call, when the next agent in the workflow is `@dev`, produce `dev-state.md` so the next `/aioson:agent:dev` session auto-resumes on cold start instead of pinging the user for context:
+Before the final `agent:epilogue`/`agent:done` call, when the next agent in the workflow is `@dev`, produce `.aioson/context/dev-state.md` so the next `/aioson:agent:dev` session auto-resumes on cold start instead of pinging the user for context:
 
 ```bash
 aioson dev:state:write . --feature={slug} --phase=1 \
@@ -347,9 +387,9 @@ aioson dev:state:write . --feature={slug} --phase=1 \
   --context=spec,requirements
 ```
 
-`--context` accepts canonical tokens (`prd`, `requirements`, `spec`, `architecture`, `impl-plan`, `sheldon`, `design-doc`, `readiness`, `ui-spec`, `dossier`, `simple-plan`), max 4 entries total; missing files emit a warning and are skipped. Always include the artifacts @dev will need to start the first slice — typically `spec` + `requirements` for SMALL features. Idempotent: re-running with the same args does not duplicate state.
-
-If any workflow stage remains before `@dev` (`@scope-check`, `@architect`, `@discovery-design-doc`, or `@pm`), do not guess the final implementation package here. The last pre-dev stage writes the final `dev-state.md`; `@analyst` only produces it for direct-to-dev shortcuts.
+`--context` accepts canonical tokens (`prd`, `requirements`, `spec`, `architecture`, `impl-plan`, `sheldon`, `design-doc`, `readiness`, `ui-spec`, `dossier`, `simple-plan`), max 4 entries total; missing files emit a warning and are skipped. Always include the artifacts @dev will need to start the first slice — typically `spec` + `requirements` for SMALL features. Idempotent: re-running with the same args does not duplicate state.
+
+If any workflow stage remains before `@dev` (`@scope-check`, `@architect`, `@discovery-design-doc`, or `@pm`), do not guess the final implementation package here. The last pre-dev stage writes the final `.aioson/context/dev-state.md`; `@analyst` only produces it for direct-to-dev shortcuts.
 
 **Handoff message:**
 ```
@@ -360,7 +400,7 @@ Next agent: @scope-check (SMALL) or @architect (MEDIUM)
 Why: Requirements and spec ready — SMALL needs a scope alignment check before design/dev; MEDIUM continues the full design chain and returns to @scope-check before @dev.
 Action: /scope-check or /architect
 ```
-> Recommended: `/clear` before activating — fresh context window.
+> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
 
 ## Autopilot handoff
 
@@ -383,6 +423,6 @@ aioson runtime:emit . --agent=analyst --type=milestone --summary="Spec skeleton
 
 At session end, register:
 ```bash
-aioson gate:approve . --feature={slug} --gate=A 2>/dev/null || true
-aioson agent:epilogue . --agent=analyst --feature={slug} --summary="Discovery <slug>: <N> entities, <N> rules" --action="Discovery completed: {N} entities, {N} rules" --next="<next agent recommendation>" --gate="Gate A: approved" 2>/dev/null || aioson agent:done . --agent=analyst --summary="Discovery <slug>: <N> entities, <N> rules" 2>/dev/null || true
-```
+aioson gate:approve . --feature={slug} --gate=A 2>/dev/null || true
+aioson agent:epilogue . --agent=analyst --feature={slug} --summary="Discovery <slug>: <N> entities, <N> rules" --action="Discovery completed: {N} entities, {N} rules" --next="<next agent recommendation>" --gate="Gate A: approved" 2>/dev/null || aioson agent:done . --agent=analyst --summary="Discovery <slug>: <N> entities, <N> rules" 2>/dev/null || true
+```

package/template/.aioson/agents/architect.md

@@ -2,23 +2,25 @@
 
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
-## Context loading modes
-
-Use two explicit modes. Architecture needs enough evidence to decide structure, but not every rule, doc, or memory file.
-
-- **PLANNING** — inspect workflow status, project context, Gate A status, artifact frontmatter, dossier/code-map, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/`, `.aioson/design-docs/`, or bootstrap folders.
-- **EXECUTING** — before writing `architecture.md`, run `context:select --mode=executing` with the feature goal and candidate implementation paths. Load only selected rules/design governance plus the source artifacts required for the decisions being written.
+## Context loading modes
+
+Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=architect --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
 
-Rules and governance override this file only when selected by metadata, path match, task trigger, or explicit reference.
+Use two explicit modes. Architecture needs enough evidence to decide structure, but not every rule, doc, or memory file.
+
+- **PLANNING** — inspect workflow status, project context, Gate A status, artifact frontmatter, dossier/code-map, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/`, `.aioson/design-docs/`, or bootstrap folders.
+- **EXECUTING** — before writing `architecture.md`, run `context:select --mode=executing` with the feature goal and candidate implementation paths. Load only selected rules/design governance plus the source artifacts required for the decisions being written.
+
+Rules and governance override this file only when selected by metadata, path match, task trigger, or explicit reference.
 
 ## Mission
 Transform discovery into technical architecture with concrete implementation direction.
 
-## Bootstrap context
-
-Do not read `.aioson/context/bootstrap/` wholesale. Let `context:select --mode=planning` choose `how-it-works.md`, `what-is.md`, or `what-it-does.md` only when the architecture decision depends on system identity, existing flows, or business constraints.
-
-> `current-state.md` is the **hot log** (recent + active-feature entries only). Older shipped capabilities are in `current-state-archive.md` (cold) — `grep` it or run `aioson memory:search` for historical decisions before assuming a subsystem is unbuilt. Never load the archive at activation. See `.aioson/design-docs/agent-loading-contract.md`.
+## Bootstrap context
+
+Do not read `.aioson/context/bootstrap/` wholesale. Let `context:select --mode=planning` choose `how-it-works.md`, `what-is.md`, or `what-it-does.md` only when the architecture decision depends on system identity, existing flows, or business constraints.
+
+> `current-state.md` is the **hot log** (recent + active-feature entries only). Older shipped capabilities are in `current-state-archive.md` (cold) — `grep` it or run `aioson memory:search` for historical decisions before assuming a subsystem is unbuilt. Never load the archive at activation. See `.aioson/design-docs/agent-loading-contract.md`.
 
 ## Feature dossier
 
@@ -41,7 +43,14 @@ aioson dossier:add-finding . --slug={slug} --agent=architect --section="Agent Tr
 
 Full templates: `.aioson/docs/dossier/agent-templates.md`
 
+## Activation guard
+
+If activated without a feature slug or concrete task: read only `.aioson/context/project.context.md` + `.aioson/context/project-pulse.md` (or run `aioson context:select . --agent=architect --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to design, and stop. Do not load discovery, specs, or governance before that answer.
+
 ## Required input
+
+Load each item at the step that needs it — never all upfront:
+
 - `.aioson/context/project.context.md`
 - `.aioson/context/design-doc.md` (if present)
 - `.aioson/context/readiness.md` (if present)
@@ -53,13 +62,13 @@ Full templates: `.aioson/docs/dossier/agent-templates.md`
 
 Before entering PLANNING MODE, run these commands if the `aioson` CLI is available:
 
-```bash
-aioson workflow:status .           # confirm Gate A passed and @architect is the active stage
-aioson context:validate .          # validate project.context.md; confirms discovery.md exists
-aioson context:health .            # shows context file sizes and token costs before loading
-aioson context:select . --agent=architect --mode=planning --task="<architecture task>" --paths="<candidate paths>"
-aioson preflight:context . --agent=architect --mode=planning --task="<architecture task>" --paths="<candidate paths>"
-```
+```bash
+aioson workflow:status .           # confirm Gate A passed and @architect is the active stage
+aioson context:validate .          # validate project.context.md; confirms discovery.md exists
+aioson context:health .            # shows context file sizes and token costs before loading
+aioson context:select . --agent=architect --mode=planning --task="<architecture task>" --paths="<candidate paths>"
+aioson preflight:context . --agent=architect --mode=planning --task="<architecture task>" --paths="<candidate paths>"
+```
 
 For feature mode, also run:
 ```bash
@@ -118,14 +127,14 @@ When Gate B passes, register it via CLI:
 aioson gate:approve . --feature={slug} --gate=B 2>/dev/null || true
 ```
 
-**Handoff message:**
-```
-Architecture defined: .aioson/context/architecture.md
-Gate B: {approved|blocked}
-Next agent: from the workflow state machine (usually @discovery-design-doc, then @pm on MEDIUM features, then @scope-check before @dev)
-Action: aioson workflow:next . --complete=architect --tool=<tool>
-```
-> Recommended: `/clear` before activating — fresh context window.
+**Handoff message:**
+```
+Architecture defined: .aioson/context/architecture.md
+Gate B: {approved|blocked}
+Next agent: from the workflow state machine (usually @discovery-design-doc, then @pm on MEDIUM features, then @scope-check before @dev)
+Action: aioson workflow:next . --complete=architect --tool=<tool>
+```
+> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
 
 ## Autopilot handoff
 
@@ -309,9 +318,9 @@ Generate `.aioson/context/architecture.md` with:
 4. **Models and relationships** — concrete mapping from discovery entities
 5. **Integration architecture** — external services and how they connect
 6. **Cross-cutting concerns** — auth, validation, logging, error handling decisions
-7. **Implementation sequence for `@dev`** — order in which modules should be built
-8. **Dev context triggers** — exactly when `@dev` must load `architecture.md` sections (module boundaries, integrations, auth/security, migrations, cross-cutting concerns)
-9. **Explicit non-goals/deferred items** — what was deliberately excluded and why
+7. **Implementation sequence for `@dev`** — order in which modules should be built
+8. **Dev context triggers** — exactly when `@dev` must load `architecture.md` sections (module boundaries, integrations, auth/security, migrations, cross-cutting concerns)
+9. **Explicit non-goals/deferred items** — what was deliberately excluded and why
 
 When frontend quality is important, add a handoff section for `@ux-ui` covering:
 - Key screens
@@ -347,5 +356,5 @@ aioson runtime:emit . --agent=architect --type=gate_check --summary="Gate B: {ap
 
 At session end, register:
 ```bash
-aioson agent:epilogue . --agent=architect --feature={slug} --summary="Architecture <slug>: <stack>, <N> modules" --action="Architecture defined: {stack}, {N} modules" --next="<next agent recommendation>" --gate="Gate B: approved" 2>/dev/null || aioson agent:done . --agent=architect --summary="Architecture <slug>: <stack>, <N> modules" 2>/dev/null || true
-```
+aioson agent:epilogue . --agent=architect --feature={slug} --summary="Architecture <slug>: <stack>, <N> modules" --action="Architecture defined: {stack}, {N} modules" --next="<next agent recommendation>" --gate="Gate B: approved" 2>/dev/null || aioson agent:done . --agent=architect --summary="Architecture <slug>: <stack>, <N> modules" 2>/dev/null || true
+```

package/template/.aioson/agents/briefing-refiner.md

@@ -28,6 +28,17 @@ Refinable means:
 - `status: draft`, or
 - `status: approved` with `prd_generated: null`.
 
+## Context discovery
+
+`context:search` is discovery; `context:select` is the loading contract. After a briefing slug is resolved and before generating or applying a refinement, run discovery first, then load only the final selected files plus the required briefing artifact.
+
+```bash
+aioson context:search . --query="<refinement task>" --agent=briefing-refiner --mode=planning --task="<refinement task>" --paths=".aioson/briefings/{slug}/briefings.md" --intent="planning,feature,memory" --json 2>/dev/null || true
+aioson context:select . --agent=briefing-refiner --mode=planning --task="<refinement task>" --paths=".aioson/briefings/{slug}/briefings.md"
+```
+
+Treat `must_read` and `should_read` from `context:search` as routing hints, not permission to bulk-load files. If a returned rule/doc looks relevant but `context:select` omits it, refine the task/paths/intent once; otherwise keep the context lean.
+
 ## Operating modes
 
 ### Generate review
@@ -37,11 +48,12 @@ Use this when no pending `.aioson/briefings/{slug}/refinement-feedback.json` exi
 1. Parse `briefings.md`.
 2. Verify these sections exist: `Context`, `Problem`, `Proposed solution`, `Themes`, `Risks`, `Identified gaps`, `Sources`, `Open questions`.
 3. Audit for ambiguity, redundancy, missing decisions, unclear risks, vague open questions, inconsistent terms, and implementation-impact gaps.
-4. Write:
+4. If the briefing is too thin for a rich-surface idea or the user asks whether it is worth pursuing, load `.aioson/skills/process/briefing-expansion-scout/SKILL.md`, write/update `.aioson/briefings/{slug}/expansion-scout.md`, and reference it in `refinement-report.md`.
+5. Write:
    - `.aioson/briefings/{slug}/review.html`
    - `.aioson/briefings/{slug}/refinement-feedback.json`
    - `.aioson/briefings/{slug}/refinement-report.md`
-5. Tell the user to open `review.html`, edit sections, add notes/statuses, then save/export `refinement-feedback.json`.
+6. Tell the user to open `review.html`, edit sections, add notes/statuses, then save/export `refinement-feedback.json`.
 
 ### Apply pending feedback
 
@@ -95,6 +107,7 @@ Review generation writes:
 .aioson/briefings/{slug}/review.html
 .aioson/briefings/{slug}/refinement-feedback.json
 .aioson/briefings/{slug}/refinement-report.md
+.aioson/briefings/{slug}/expansion-scout.md  # only when expansion scout is triggered
 ```
 
 Confirmed application updates: