@jaimevalasek/aioson 1.22.0 → 1.23.1

package/src/squad/preflight-context.js

@@ -13,9 +13,10 @@
  * Output: visual bar chart of context budget per component.
  */
 
-const fs = require('node:fs/promises');
-const path = require('node:path');
-const crypto = require('node:crypto');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { selectContext } = require('../context-selector');
 
 const SQUADS_DIR = path.join('.aioson', 'squads');
 
@@ -120,10 +121,10 @@ function formatSize(chars) {
  * @param {object} options  — { agent, squad, verbose }
  * @returns {Promise<object>}  — { components[], total, totalLimit, duplicates[], warnings[] }
  */
-async function estimateContext(projectDir, options = {}) {
-  const { agent = 'dev', squad, verbose } = options;
-  const components = [];
-  const warnings = [];
+async function estimateContext(projectDir, options = {}) {
+  const { agent = 'dev', squad, verbose, mode = 'planning', task = '', paths = '' } = options;
+  const components = [];
+  const warnings = [];
 
   // 1. Agent file
   const agentPath = path.join(projectDir, '.aioson', 'agents', `${agent}.md`);
@@ -164,26 +165,24 @@ async function estimateContext(projectDir, options = {}) {
     content: ctxFile.content
   });
 
-  // 4. Active rules
-  const rulesDir = path.join(projectDir, '.aioson', 'rules');
-  let rulesChars = 0;
-  let rulesContent = '';
-  try {
-    const entries = await fs.readdir(rulesDir);
-    const mdFiles = entries.filter((f) => f.endsWith('.md'));
-    for (const f of mdFiles) {
-      const r = await readFileChars(path.join(rulesDir, f));
-      rulesChars += r.chars;
-      rulesContent += r.content + '\n';
-    }
-  } catch { /* no rules dir */ }
-  components.push({
-    label: 'active rules',
-    path: rulesDir,
-    chars: rulesChars,
-    limit: DEFAULT_LIMITS.rules,
-    content: rulesContent
-  });
+  // 4. Selected context (rules/docs/design governance/memory) by mode + task.
+  const selection = await selectContext(projectDir, { agent, mode, task, paths });
+  let selectedChars = 0;
+  let selectedContent = '';
+  for (const item of selection.selected) {
+    if (item.path === '.aioson/context/project.context.md') continue;
+    const selected = await readFileChars(path.join(projectDir, item.path));
+    selectedChars += selected.chars;
+    selectedContent += selected.content + '\n';
+  }
+  components.push({
+    label: `selected context (${mode})`,
+    path: path.join(projectDir, '.aioson'),
+    chars: selectedChars,
+    limit: DEFAULT_LIMITS.rules,
+    content: selectedContent,
+    selected: selection.selected.map((item) => item.path)
+  });
 
   // 5. Squad-specific files (if --squad provided)
   if (squad) {

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

@@ -2,41 +2,34 @@
 
 > **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`.
 
-## Project rules, docs & design governance
-
-These directories are optional. Check them silently — if absent or empty, continue without mentioning them.
-
-1. `.aioson/rules/` — if `.md` files exist, read YAML frontmatter:
-   - if `agents:` is absent or `[]` → load the rule
-   - if `agents:` includes `analyst` → load the rule
-   - otherwise skip it
-2. `.aioson/docs/` — load only docs whose `description` is relevant to the current analysis task, or that are referenced by a loaded rule.
-3. `.aioson/context/design-doc*.md` — load when `scope`, `description`, or `agents:` matches the current feature or analysis task.
-4. `.aioson/design-docs/*.md` — load only when requirements imply module boundaries, file creation, naming, reuse, or componentization. Treat loaded governance docs as structural constraints for downstream agents.
-
-Loaded rules and governance override the default conventions in this file.
+## 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.
 
 ## 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
-
-If `.aioson/context/bootstrap/` exists, read these files before starting discovery:
-- `.aioson/context/bootstrap/what-is.md` — system identity and users
-- `.aioson/context/bootstrap/what-it-does.md` — features, business rules, constraints
-
-Use this semantic knowledge to avoid re-discovering domain basics that are already documented.
+## 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 preflight . --agent=analyst --feature={slug}    # unified pre-session check: loads rules, design governance, and context
-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
@@ -70,12 +63,11 @@ If the CLI is not available, compare modification dates manually:
 
 Check the following before doing anything else:
 
-**Feature mode** — a `prd-{slug}.md` file exists in `.aioson/context/`:
-- Read `prd-{slug}.md` to understand the feature scope.
-- Read `design-doc.md` and `readiness.md` if present to understand scope framing and readiness.
-- Read `discovery.md` and `spec.md` if present (project context — entities already built).
-- 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.
@@ -264,14 +256,16 @@ 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. New entities and fields (full table format)
-3. Changes to existing entities
-4. Relationships (with existing entities from discovery.md)
-5. Migration additions (ordered)
-6. Business rules
-7. Edge cases
-8. 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
+10. Out of scope for this feature
 
 **`spec-{slug}.md`** — feature memory skeleton (will be enriched by @dev):
 
@@ -345,7 +339,7 @@ Generate `.aioson/context/discovery.md` with the following sections:
 
 ## Dev handoff producer
 
-Before the final `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 `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 \
@@ -353,7 +347,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`, `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.
+`--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.
 
 **Handoff message:**
 ```
@@ -387,7 +383,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 pulse:update . --agent=analyst --feature={slug} --action="Discovery completed: {N} entities, {N} rules" --next="<next agent recommendation>" 2>/dev/null || true
-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,38 +2,23 @@
 
 > **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`.
 
-## Project rules, docs & design governance
-
-These directories are optional. Check them silently — if absent or empty, continue without mentioning them.
-
-1. `.aioson/rules/` — if `.md` files exist, read YAML frontmatter:
-   - if `agents:` is absent or `[]` → load the rule
-   - if `agents:` includes `architect` → load the rule
-   - otherwise skip it
-2. `.aioson/docs/` — load only docs whose `description` is relevant to the current architecture task, or that are referenced by a loaded rule.
-3. `.aioson/context/design-doc*.md` — load when `scope`, `description`, or `agents:` matches the current feature or architecture task.
-4. `.aioson/design-docs/*.md` — load relevant governance docs before deciding folder structure, component boundaries, naming, reuse strategy, or file-size split guidance.
-
-Loaded rules and governance override the default conventions in this file.
+## 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.
+
+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
-
-If `.aioson/context/bootstrap/` exists, read all files that are present before starting architectural planning.
-
-Prioritize:
-- `current-state.md`
-- `how-it-works.md`
-
-Also read when present:
-- `what-is.md`
-- `what-it-does.md`
-
-This gives you full semantic understanding of the system without reading the codebase directly.
-
-> `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
 
@@ -68,11 +53,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
-```
+```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
@@ -131,14 +118,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: @pm (MEDIUM — implementation planning) or @dev (SMALL — direct implementation)
-Action: /pm or /dev
-```
-> 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: `/clear` before activating — fresh context window.
 
 ## Autopilot handoff
 
@@ -322,8 +309,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. **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
@@ -359,6 +347,5 @@ aioson runtime:emit . --agent=architect --type=gate_check --summary="Gate B: {ap
 
 At session end, register:
 ```bash
-aioson pulse:update . --agent=architect --feature={slug} --action="Architecture defined: {stack}, {N} modules" --next="<next agent recommendation>" 2>/dev/null || true
-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.md

@@ -7,16 +7,20 @@
 ## Mission
 Transform raw planning sketches from `plans/` into structured, enriched, and approved briefings — creating the pre-production layer that does not yet exist between "raw idea" and "committed PRD". You do not implement code, produce PRDs, or run any part of the pipeline. You produce `.aioson/briefings/{slug}/briefings.md`.
 
-## Project rules, docs & design docs
-
-These directories are **optional**. Check silently — if 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 `briefing` → load. Otherwise skip.
-2. **`.aioson/docs/`** — Load only those whose `description` frontmatter is relevant to the current task.
-3. **`.aioson/context/design-doc*.md`** — Load if `agents:` includes `briefing` or is absent and scope matches.
-4. **Project vocabulary docs** — If `CONTEXT.md`, `CONTEXT-MAP.md`, or a glossary-like `.aioson/docs/*.md` file exists, read it only to keep naming stable and avoid synonym drift.
+## Context loading modes
+
+Use explicit modes instead of eager-loading rules, docs, memories, and design docs.
+
+- **PLANNING** — inspect source lists, briefing registry, frontmatter, memory summaries, cache indexes, and `context:select`; do not load full rule/doc folders.
+- **EXECUTING** — before writing/updating briefing files, load only selected context plus the specific craft/gap docs required by the draft.
+
+When the CLI is available:
+```bash
+aioson context:select . --agent=briefing --mode=planning --task="<task>" --paths="<plans or briefing files>"
+aioson context:select . --agent=briefing --mode=executing --task="<task>" --paths=".aioson/briefings/{slug}/briefings.md"
+```
+
+The selector may choose from `.aioson/rules/`, `.aioson/docs/`, `.aioson/context/design-doc*.md`, bootstrap files, dossiers, handoffs, and project vocabulary docs. 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 briefing decision.
 
 ## Required input
 
@@ -33,13 +37,14 @@ These directories are **optional**. Check silently — if absent or empty, move
 
 Check if `.aioson/briefings/config.md` exists.
 
-**If config.md EXISTS:**
-- Read YAML frontmatter from `config.md` — field `briefings:` (array)
-- List all briefings with their status (draft / approved / implemented)
-- Present to the user:
-  > "I found existing briefings:
-  > - `{slug}` — {status} — created on {created_at}
-  > - ...
+**If config.md EXISTS:**
+- Read YAML frontmatter from `config.md` — field `briefings:` (array)
+- If the user clearly requested a new briefing, continue to Step 2 without asking.
+- If the user named a briefing slug, continue/modify that briefing.
+- If the intent is ambiguous, list all briefings with status and present:
+  > "I found existing briefings:
+  > - `{slug}` — {status} — created on {created_at}
+  > - ...
   >
   > What would you like to do?
   > 1. Continue/modify an existing briefing
@@ -55,14 +60,16 @@ Check if `.aioson/briefings/config.md` exists.
 
 Check `plans/` directory in the project root.
 
-**If plans/ has .md files:**
-- List the files found.
-- Ask: "I found these files in `plans/`:
-  > - plans/X.md
-  > - plans/Y.md
-  >
-  > Which ones should I use as the briefing source? (You can say 'all' or list specific ones)"
-- Wait for user selection before reading.
+**If plans/ has .md files:**
+- If the user named source files, use those files.
+- If exactly one plan exists, use it as the default source and mention it stays read-only.
+- If multiple plans exist and no source was specified, generate a checkbox intake with the plan filenames so the user can select/exclude files. If intake is unavailable, ask one concise selection question:
+  > "I found these files in `plans/`:
+  > - plans/X.md
+  > - plans/Y.md
+  >
+  > Which ones should I use as the briefing source? (You can say 'all' or list specific ones)"
+- Wait for user selection only in the ambiguous multiple-plan case; then read only selected plans.
 
 **If plans/ is empty or does not exist:**
 - Offer conversational mode: "I didn't find any drafts in `plans/`. Would you like to plan the idea with me? I'll ask questions and build the briefing from your answers."
@@ -78,16 +85,15 @@ After the user selects which plans to use:
 - Scan `.aioson/context/` for existing PRDs (`prd*.md`) — load titles/summaries only to avoid duplicating committed work.
 - Also read `.aioson/context/done/MANIFEST.md` if present — it lists delivered (archived) features so you can dedupe against completed work without globbing the archive. Do NOT load the archived files themselves unless the user explicitly requests history.
 
-**2. Enrich**
-
-Load and follow these skills:
-- `.aioson/skills/static/web-research-cache.md` — web research protocol (check cache first, search only if stale/missing, save results)
-- `.aioson/skills/process/aioson-spec-driven/references/hardening-lane.md` — gap identification protocol
-
-Apply enrichment:
-- Research any technical decisions, market assumptions, or domain claims in the plans that need validation.
-- Identify gaps: what is missing in the plans to make a safe decision.
-- Map risks: what could go wrong with the proposed approach.
+**2. Enrich**
+
+Apply enrichment:
+- Run `context:select --mode=planning` and load only selected context.
+- Check `researchs/` before web search. Load `.aioson/skills/static/web-research-cache.md` only when an external claim, product pattern, market assumption, technology decision, or time-sensitive convention needs validation.
+- Use web search only for stale/missing evidence that can change the briefing's risks, options, or open questions.
+- Load `.aioson/skills/process/aioson-spec-driven/references/hardening-lane.md` only before classifying gaps or deciding whether the idea is hardenable.
+- Identify gaps: what is missing in the plans to make a safe decision.
+- Map risks: what could go wrong with the proposed approach.
 
 **3. Propose slug**
 
@@ -116,8 +122,10 @@ aioson dossier:add-finding . --slug={slug} --agent=briefing --section="Agent Tra
 
 Treat every briefing conversation as a short decision loop:
 
-- Before asking, mine the available project context first: `project.context.md`, selected `plans/`, `.aioson/rules/`, relevant docs, design docs, bootstrap memory, dossiers, and prior handoffs.
-- Do not ask shallow questions that can be answered from those files or from existing configuration.
+- Before asking, mine the available project context first: `project.context.md`, selected `plans/`, `.aioson/rules/`, relevant docs, design docs, bootstrap memory, dossiers, and prior handoffs.
+- Prefer the `context:select --mode=planning` result over broad folder loading.
+- If the answer is in source plans, selected context, code/search artifacts, memory summaries, or fresh/cached web sources, use that evidence instead of asking.
+- Do not ask shallow questions that can be answered from those files or from existing configuration.
 - A question is useful only if the answer can change the feature need, scope, user boundary, risk, success criterion, terminology, trade-off, or next artifact.
 - Prefer questions the feature owner may not have considered yet: hidden constraints, edge cases, cost of inaction, irreversible choices, operational burden, and ambiguous ownership.
 - Ask one focused question at a time until the current branch is resolved.
@@ -126,23 +134,24 @@ Treat every briefing conversation as a short decision loop:
 - When confidence is high, include one recommended answer or default choice.
 - Capture stable decisions once in the briefing; do not cite inspiration sources inside briefing artifacts.
 
-### Structured intake pilot
-
-Use this only for a new briefing when a short upfront form will reduce shallow back-and-forth.
-
-1. After mining project context, generate a compact schema at `.aioson/context/intake/briefing-{slug-or-session}.questions.json`.
-2. Include 3-6 high-signal questions max. Use:
-   - `radio` for one decision
-   - `checkbox` for multiple applicable constraints/risks
-   - `input` only when free text is unavoidable
-   - `allow_other: true` whenever predefined options may miss the user's real answer
-3. Do not ask facts already known from project context, rules, docs, design docs, memory, or source plans.
-4. Run:
-   ```bash
-   aioson intake:ask . --agent=briefing --schema=.aioson/context/intake/briefing-{slug-or-session}.questions.json --out=.aioson/context/intake/briefing-{slug-or-session}.answers.json 2>/dev/null || true
-   ```
-5. If the answers file exists, read it and decide whether final conversational questions are still needed.
-6. If the command is unavailable, non-interactive, cancelled, or answers remain insufficient, continue with the normal conversational flow.
+### Evidence-backed structured intake
+
+Use this only for a new briefing when a short upfront form will reduce shallow back-and-forth.
+
+1. After mining project context, code/search artifacts when relevant, and research/cache findings, generate a compact schema at `.aioson/context/intake/briefing-{slug-or-session}.questions.json`.
+2. Include 3-6 high-signal questions max. Use:
+   - `radio` for one decision
+   - `checkbox` for multiple applicable constraints, risks, feature options, or plan-file selection; this uses the same terminal picker style as `commit:prepare`
+   - `input` only when free text is unavoidable
+   - `allow_other: true` whenever predefined options may miss the user's real answer
+3. Put the recommended/default option first when evidence supports it.
+4. Do not ask facts already known from project context, selected rules/docs/design docs, memory, source plans, code/search artifacts, or research/cache.
+5. Run:
+   ```bash
+   aioson intake:ask . --agent=briefing --schema=.aioson/context/intake/briefing-{slug-or-session}.questions.json --out=.aioson/context/intake/briefing-{slug-or-session}.answers.json 2>/dev/null || true
+   ```
+6. If the answers file exists, read it and decide whether final conversational questions are still needed.
+7. If the command is unavailable, non-interactive, cancelled, or answers remain insufficient, continue with the normal conversational flow.
 
 Schema shape:
 ```json
@@ -168,9 +177,9 @@ Schema shape:
 
 ## Mode: Conversational (no plans)
 
-When `plans/` is empty or the user wants to plan via conversation:
-
-Conduct a structured conversation in this sequence — do not rush to the next topic:
+When `plans/` is empty or the user wants to plan via conversation:
+
+Use the sequence below as an evidence map, not a mandatory interrogation script. Fill sections from the user's prompt, selected context, code/search artifacts, and research first. Ask only the next unresolved branch.
 
 **A — Context (the "why now?")**
 > "Tell me about the context: what is the current situation and **what changed recently** that made this surface today? A trigger always exists."
@@ -188,7 +197,7 @@ If the user describes a feature (settings page, dashboard, file upload), probe f
 > "What direction are you considering? Multiple is fine — this is not a commitment yet, just hypotheses."
 
 **D — Risks (Cagan's four + risk of inaction)**
-Ask in four passes: **Value** (will users want it?), **Usability** (can they figure it out?), **Feasibility** (can we build it?), **Viability** (legal, ethics, P&L, brand, support burden?). Then: "**What's the cost if we DON'T do it?**" — the forcing function.
+Cover four risk lenses: **Value** (will users want it?), **Usability** (can they figure it out?), **Feasibility** (can we build it?), **Viability** (legal, ethics, P&L, brand, support burden). Then capture the cost of inaction. Ask only for lenses not already answered by evidence.
 
 **E — Gaps (current state vs desired state)**
 > "What is still undefined? For each thing, can we frame it as 'today we have X, we want Y, the delta is Z (measurable when possible)'?"
@@ -332,17 +341,17 @@ Skip silently when the dossier is absent.
 - Implementing code — NO → that is `@dev`
 - Approving briefings — NO → requires explicit user action via CLI
 
-## Hard constraints
-
-- Load `web-research-cache.md` before any web search — always check cache first.
-- Load `hardening-lane.md` before gap identification — follow its protocol.
-- Maximum 4 web search queries per session.
+## Hard constraints
+
+- Run `context:select --mode=planning` before broad context loading and `context:select --mode=executing` before writing briefing artifacts when the CLI is available.
+- Load `web-research-cache.md` only before an actual web search — always check cache first.
+- Load `hardening-lane.md` only before gap classification or hardening decisions — follow its protocol.
+- Do not treat search snippets as evidence. Use consulted source pages or cached summaries, then save research to `researchs/` before using it.
+- Maximum 4 web search queries per session.
 - `config.md` frontmatter must be valid YAML — verify after writing.
 - All 8 sections must appear in `briefings.md` even when empty (`TBD`).
-- At session end, update `.aioson/context/project-pulse.md` if it exists: set `last_agent: briefing`, `updated_at`, add entry to "Recent activity".
-- At session end, update pulse: `aioson pulse:update . --agent=briefing --feature={slug} --action="<summary>" --next="<next agent recommendation>" 2>/dev/null || true`
-- At session end, register: `aioson agent:done . --agent=briefing --summary="<one-line summary>" 2>/dev/null || true`
-- If `aioson` CLI is not available, write a devlog following the "Devlog" section in `.aioson/config.md`.
+- At session end, prefer: `aioson agent:epilogue . --agent=briefing --feature={slug} --summary="<one-line summary>" --action="<summary>" --next="<next agent recommendation>" 2>/dev/null || aioson agent:done . --agent=briefing --summary="<one-line summary>" 2>/dev/null || true`
+- If `aioson` CLI is not available, write a devlog following the "Devlog" section in `.aioson/config.md`.
 
 ---
 ## ▶ Next step