@jaimevalasek/aioson 1.23.0 → 1.23.3

package/src/i18n/messages/en.js

@@ -21,12 +21,16 @@ module.exports = {
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=en]',
     help_agent_help:
       'aioson agent:help [agent] [--json]',
-    help_agent_invoke:
-      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=en]',
+    help_agent_invoke:
+      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=en]',
+    help_agent_epilogue:
+      'aioson agent:epilogue [path] --agent=<agent> --summary=<text> [--feature=<slug>] [--approve-gate=A|B|C|D] [--json] [--locale=en]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=en]',
-    help_context_pack:
-      'aioson context:pack [path] [--agent=<agent>] [--goal=<text>] [--module=<module-or-folder>] [--max-files=8] [--json] [--locale=en]',
-    help_context_load:
+    help_context_pack:
+      'aioson context:pack [path] [--agent=<agent>] [--goal=<text>] [--module=<module-or-folder>] [--max-files=8] [--json] [--locale=en]',
+    help_context_select:
+      'aioson context:select [path] [--agent=<agent>] [--mode=planning|executing] [--task=<text>] [--paths=<path[,path2]>] [--feature=<slug>] [--json] [--locale=en]',
+    help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<name> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=en]',
     help_chain_audit:
       'aioson chain:audit <file> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=en]',
@@ -118,8 +122,10 @@ module.exports = {
       'aioson workflow:next [path] [--complete[=<agent>]] [--agent=<agent>] [--skip=<agent>] [--status] [--suggest] [--tool=codex|claude|opencode] [--json] [--locale=en]',
     help_workflow_status:
       'aioson workflow:status [path] [--suggest] [--tool=codex|claude|opencode] [--json] [--locale=en]',
-    help_workflow_execute:
-      'aioson workflow:execute [path] [--steps=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=en]',
+    help_workflow_execute:
+      'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=en]',
+    help_review_cycle:
+      'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=en]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=en]',
     help_parallel_doctor:

package/src/i18n/messages/es.js

@@ -22,12 +22,16 @@ module.exports = {
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=es]',
     help_agent_help:
       'aioson agent:help [agent] [--json]',
-    help_agent_invoke:
-      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=es]',
+    help_agent_invoke:
+      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=es]',
+    help_agent_epilogue:
+      'aioson agent:epilogue [path] --agent=<agente> --summary=<texto> [--feature=<slug>] [--approve-gate=A|B|C|D] [--json] [--locale=es]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=es]',
-    help_context_pack:
-      'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-o-carpeta>] [--max-files=8] [--json] [--locale=es]',
-    help_context_load:
+    help_context_pack:
+      'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-o-carpeta>] [--max-files=8] [--json] [--locale=es]',
+    help_context_select:
+      'aioson context:select [path] [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<ruta[,ruta2]>] [--feature=<slug>] [--json] [--locale=es]',
+    help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nombre> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=es]',
     help_chain_audit:
       'aioson chain:audit <archivo> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=es]',
@@ -108,8 +112,10 @@ module.exports = {
       'aioson test:package [source-path] [--keep] [--dry-run] [--json] [--locale=es]',
     help_workflow_plan:
       'aioson workflow:plan [path] [--classification=MICRO|SMALL|MEDIUM] [--json] [--locale=es]',
-    help_workflow_execute:
-      'aioson workflow:execute [path] [--steps=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=es]',
+    help_workflow_execute:
+      'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=es]',
+    help_review_cycle:
+      'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=es]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=es]',
     help_parallel_doctor:

package/src/i18n/messages/fr.js

@@ -22,12 +22,16 @@ module.exports = {
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=fr]',
     help_agent_help:
       'aioson agent:help [agent] [--json]',
-    help_agent_invoke:
-      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=fr]',
+    help_agent_invoke:
+      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=fr]',
+    help_agent_epilogue:
+      'aioson agent:epilogue [path] --agent=<agent> --summary=<texte> [--feature=<slug>] [--approve-gate=A|B|C|D] [--json] [--locale=fr]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=fr]',
-    help_context_pack:
-      'aioson context:pack [path] [--agent=<agent>] [--goal=<texte>] [--module=<module-ou-dossier>] [--max-files=8] [--json] [--locale=fr]',
-    help_context_load:
+    help_context_pack:
+      'aioson context:pack [path] [--agent=<agent>] [--goal=<texte>] [--module=<module-ou-dossier>] [--max-files=8] [--json] [--locale=fr]',
+    help_context_select:
+      'aioson context:select [path] [--agent=<agent>] [--mode=planning|executing] [--task=<texte>] [--paths=<chemin[,chemin2]>] [--feature=<slug>] [--json] [--locale=fr]',
+    help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nom> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=fr]',
     help_chain_audit:
       'aioson chain:audit <fichier> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=fr]',
@@ -108,8 +112,10 @@ module.exports = {
       'aioson test:package [source-path] [--keep] [--dry-run] [--json] [--locale=fr]',
     help_workflow_plan:
       'aioson workflow:plan [path] [--classification=MICRO|SMALL|MEDIUM] [--json] [--locale=fr]',
-    help_workflow_execute:
-      'aioson workflow:execute [path] [--steps=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=fr]',
+    help_workflow_execute:
+      'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=fr]',
+    help_review_cycle:
+      'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=fr]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=fr]',
     help_parallel_doctor:

package/src/i18n/messages/pt-BR.js

@@ -22,12 +22,16 @@ module.exports = {
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=pt-BR]',
     help_agent_help:
       'aioson agent:help [agent] [--json]',
-    help_agent_invoke:
-      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=pt-BR]',
+    help_agent_invoke:
+      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=pt-BR]',
+    help_agent_epilogue:
+      'aioson agent:epilogue [path] --agent=<agente> --summary=<texto> [--feature=<slug>] [--approve-gate=A|B|C|D] [--json] [--locale=pt-BR]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=pt-BR]',
-    help_context_pack:
-      'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-ou-pasta>] [--max-files=8] [--json] [--locale=pt-BR]',
-    help_context_load:
+    help_context_pack:
+      'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-ou-pasta>] [--max-files=8] [--json] [--locale=pt-BR]',
+    help_context_select:
+      'aioson context:select [path] [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<caminho[,caminho2]>] [--feature=<slug>] [--json] [--locale=pt-BR]',
+    help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nome> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=pt-BR]',
     help_chain_audit:
       'aioson chain:audit <arquivo> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=pt-BR]',
@@ -120,8 +124,10 @@ module.exports = {
       'aioson workflow:next [path] [--complete[=<agente>]] [--agent=<agente>] [--skip=<agente>] [--status] [--suggest] [--tool=codex|claude|opencode] [--json] [--locale=pt-BR]',
     help_workflow_status:
       'aioson workflow:status [path] [--suggest] [--tool=codex|claude|opencode] [--json] [--locale=pt-BR]',
-    help_workflow_execute:
-      'aioson workflow:execute [path] [--steps=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=pt-BR]',
+    help_workflow_execute:
+      'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=pt-BR]',
+    help_review_cycle:
+      'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=pt-BR]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=pt-BR]',
     help_parallel_doctor:

package/src/parser.js

@@ -29,7 +29,7 @@ function parseArgv(argv) {
         'all', 'force', 'dry-run', 'no-interactive', 'fix', 'json',
         'help', 'version', 'no-launch', 'attach', 'tmux',
         'allow-warnings', 'install-hook', 'uninstall-hook', 'remove-hook',
-        'agent-safe',
+        'agent-safe', 'agentic',
         'selective',
         'status', 'suggest', 'apply',
         'runtime-only', 'template-only', 'inception', 'locales',

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
+```