@jaimevalasek/aioson 1.17.3 → 1.19.0

package/src/i18n/messages/en.js

@@ -19,6 +19,8 @@ module.exports = {
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=en]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|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|gemini|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=en]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=en]',
@@ -219,7 +221,7 @@ module.exports = {
     help_runtime_emit:
       'aioson runtime:emit [path] --agent=<name> [--type=<event>] [--summary=<text>] [--title=<text>] [--refs=<file[,file2]>] [--plan-step=<id>] [--meta=<json>] [--json] [--locale=en]',
     help_live_start:
-      'aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<name> [--tool-bin=<binary>] [--tool-args=<args>] [--title=<text>] [--goal=<text>] [--plan=<file>] [--session=<key>] [--message=<text>] [--attach] [--no-launch] [--tmux] [--json] [--locale=en]',
+      'aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<name> [--tool-bin=<binary>] [--permission-mode=default|yolo] [--tool-args=<args>] [--title=<text>] [--goal=<text>] [--plan=<file>] [--session=<key>] [--message=<text>] [--attach] [--no-launch] [--tmux] [--json] [--locale=en]',
     help_live_status:
       'aioson live:status [path] [--agent=<name>] [--limit=8] [--watch=2] [--format=compact|tmux-bar] [--json] [--locale=en]',
     help_live_handoff:
@@ -505,7 +507,22 @@ module.exports = {
       'Pentester app_target requires --feature=<slug> (or --slug=<slug>).',
     prompt_missing_scope_for_app_target:
       'Pentester app_target requires --scope=<area>.',
-    prompt_title: 'Prompt for agent "{agent}" on tool "{tool}" (locale: {locale}):'
+    prompt_title: 'Prompt for agent "{agent}" on tool "{tool}" (locale: {locale}):',
+    help_available: 'Available agents:',
+    help_run_detail: 'Run "aioson agent:help <name>" for details on a specific agent.',
+    help_usage: 'Usage:',
+    help_claude_code: '(Claude Code)',
+    help_common_options: 'Common options:',
+    help_opt_tool: 'Target tool (codex|claude|gemini|opencode)',
+    help_opt_language: 'Interaction language (e.g., pt-BR, en)',
+    help_opt_headless: 'Output prompt only, no runtime tracking',
+    help_opt_output: 'Save headless prompt to file',
+    help_opt_json: 'JSON output mode',
+    help_agent_options: 'Agent-specific options ({command}):',
+    help_requires: 'Requires:',
+    help_produces: 'Produces:',
+    help_instruction_file: 'Instruction file:',
+    help_unknown_agent: 'Unknown agent: {agent}'
   },
   context_validate: {
     missing_file: 'Context file not found: {path}',
@@ -1093,6 +1110,7 @@ module.exports = {
     json_requires_no_launch: '--json requires --no-launch for live:start because foreground launch is interactive.',
     tool_binary_not_found: 'Tool binary not found in PATH: {binary}',
     tool_mismatch: 'Active session uses tool "{existing}" but --tool={requested} was given. Close the session first or use the same tool.',
+    tool_mismatch_auto_closed: 'Previous live session used "{existing}" and was auto-closed. Starting a new session with "{requested}".',
     micro_task_already_open: 'A live micro-task is already open for {agent}. Emit task_completed before task_started again.',
     handoff_same_agent: 'live:handoff requires different --agent and --to values.',
     handoff_agent_mismatch: 'No active live session found for {agent}.',

package/src/i18n/messages/es.js

@@ -20,6 +20,8 @@ module.exports = {
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=es]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|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|gemini|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=es]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=es]',
@@ -383,7 +385,22 @@ module.exports = {
       'Pentester app_target requiere --feature=<slug> (o --slug=<slug>).',
     prompt_missing_scope_for_app_target:
       'Pentester app_target requiere --scope=<area>.',
-    prompt_title: 'Prompt para el agente "{agent}" en la herramienta "{tool}" (locale: {locale}):'
+    prompt_title: 'Prompt para el agente "{agent}" en la herramienta "{tool}" (locale: {locale}):',
+    help_available: 'Agentes disponibles:',
+    help_run_detail: 'Ejecute "aioson agent:help <nombre>" para detalles de un agente específico.',
+    help_usage: 'Uso:',
+    help_claude_code: '(Claude Code)',
+    help_common_options: 'Opciones comunes:',
+    help_opt_tool: 'Herramienta destino (codex|claude|gemini|opencode)',
+    help_opt_language: 'Idioma de interacción (ej: pt-BR, en)',
+    help_opt_headless: 'Solo salida del prompt, sin rastreo de runtime',
+    help_opt_output: 'Guardar prompt headless en archivo',
+    help_opt_json: 'Modo de salida JSON',
+    help_agent_options: 'Opciones específicas del agente ({command}):',
+    help_requires: 'Requiere:',
+    help_produces: 'Produce:',
+    help_instruction_file: 'Archivo de instrucción:',
+    help_unknown_agent: 'Agente desconocido: {agent}'
   },
   context_validate: {
     missing_file: 'Archivo de contexto no encontrado: {path}',

package/src/i18n/messages/fr.js

@@ -20,6 +20,8 @@ module.exports = {
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=fr]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|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|gemini|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=fr]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=fr]',
@@ -382,7 +384,22 @@ module.exports = {
       'Pentester app_target exige --feature=<slug> (ou --slug=<slug>).',
     prompt_missing_scope_for_app_target:
       'Pentester app_target exige --scope=<area>.',
-    prompt_title: 'Prompt pour l agent "{agent}" sur l outil "{tool}" (locale : {locale}) :'
+    prompt_title: 'Prompt pour l agent "{agent}" sur l outil "{tool}" (locale : {locale}) :',
+    help_available: 'Agents disponibles :',
+    help_run_detail: 'Exécutez "aioson agent:help <nom>" pour les détails d un agent spécifique.',
+    help_usage: 'Utilisation :',
+    help_claude_code: '(Claude Code)',
+    help_common_options: 'Options communes :',
+    help_opt_tool: 'Outil cible (codex|claude|gemini|opencode)',
+    help_opt_language: 'Langue d interaction (ex : pt-BR, en)',
+    help_opt_headless: 'Sortie du prompt uniquement, sans suivi runtime',
+    help_opt_output: 'Enregistrer le prompt headless dans un fichier',
+    help_opt_json: 'Mode de sortie JSON',
+    help_agent_options: 'Options spécifiques de l agent ({command}) :',
+    help_requires: 'Requiert :',
+    help_produces: 'Produit :',
+    help_instruction_file: 'Fichier d instruction :',
+    help_unknown_agent: 'Agent inconnu : {agent}'
   },
   context_validate: {
     missing_file: 'Fichier de contexte introuvable : {path}',

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

@@ -20,6 +20,8 @@ module.exports = {
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=pt-BR]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|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|gemini|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=pt-BR]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=pt-BR]',
@@ -217,7 +219,7 @@ module.exports = {
     help_runtime_emit:
       'aioson runtime:emit [path] --agent=<nome> [--type=<evento>] [--summary=<texto>] [--title=<texto>] [--refs=<arquivo[,arquivo2]>] [--plan-step=<id>] [--meta=<json>] [--json] [--locale=pt-BR]',
     help_live_start:
-      'aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<nome> [--tool-bin=<binario>] [--tool-args=<args>] [--title=<texto>] [--goal=<texto>] [--plan=<arquivo>] [--session=<chave>] [--message=<texto>] [--attach] [--no-launch] [--tmux] [--json] [--locale=pt-BR]',
+      'aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<nome> [--tool-bin=<binario>] [--permission-mode=default|yolo] [--tool-args=<args>] [--title=<texto>] [--goal=<texto>] [--plan=<arquivo>] [--session=<chave>] [--message=<texto>] [--attach] [--no-launch] [--tmux] [--json] [--locale=pt-BR]',
     help_live_status:
       'aioson live:status [path] [--agent=<nome>] [--limit=8] [--watch=2] [--format=compact|tmux-bar] [--json] [--locale=pt-BR]',
     help_live_handoff:
@@ -477,7 +479,22 @@ module.exports = {
       'Pentester app_target exige --feature=<slug> (ou --slug=<slug>).',
     prompt_missing_scope_for_app_target:
       'Pentester app_target exige --scope=<area>.',
-    prompt_title: 'Prompt para o agente "{agent}" na ferramenta "{tool}" (locale: {locale}):'
+    prompt_title: 'Prompt para o agente "{agent}" na ferramenta "{tool}" (locale: {locale}):',
+    help_available: 'Agentes disponíveis:',
+    help_run_detail: 'Execute "aioson agent:help <nome>" para detalhes de um agente específico.',
+    help_usage: 'Uso:',
+    help_claude_code: '(Claude Code)',
+    help_common_options: 'Opções comuns:',
+    help_opt_tool: 'Ferramenta alvo (codex|claude|gemini|opencode)',
+    help_opt_language: 'Idioma de interação (ex: pt-BR, en)',
+    help_opt_headless: 'Saída apenas do prompt, sem rastreamento de runtime',
+    help_opt_output: 'Salvar prompt headless em arquivo',
+    help_opt_json: 'Modo de saída JSON',
+    help_agent_options: 'Opções específicas do agente ({command}):',
+    help_requires: 'Requer:',
+    help_produces: 'Produz:',
+    help_instruction_file: 'Arquivo de instrução:',
+    help_unknown_agent: 'Agente desconhecido: {agent}'
   },
   context_validate: {
     missing_file: 'Arquivo de contexto nao encontrado: {path}',
@@ -1119,6 +1136,7 @@ module.exports = {
     json_requires_no_launch: '--json requer --no-launch para live:start porque o lancamento em primeiro plano e interativo.',
     tool_binary_not_found: 'Binario da ferramenta nao encontrado no PATH: {binary}',
     tool_mismatch: 'A sessao ativa usa a ferramenta "{existing}" mas --tool={requested} foi informado. Encerre a sessao primeiro ou use a mesma ferramenta.',
+    tool_mismatch_auto_closed: 'A sessao live anterior usava "{existing}" e foi fechada automaticamente. Iniciando nova sessao com "{requested}".',
     micro_task_already_open: 'Uma micro-tarefa live ja esta aberta para {agent}. Emita task_completed antes de task_started novamente.',
     handoff_same_agent: 'live:handoff requer valores diferentes para --agent e --to.',
     handoff_agent_mismatch: 'Nenhuma sessao live ativa encontrada para {agent}.',

package/src/lib/dev-resume.js

@@ -121,6 +121,10 @@ async function buildDevResumeData(projectPath) {
     ? lastHandoff.artifact_uris
     : [];
 
+  const decisionRationale = Array.isArray(lastHandoff && lastHandoff.decision_rationale)
+    ? lastHandoff.decision_rationale
+    : [];
+
   return {
     feature_slug: featureSlug,
     classification,
@@ -128,7 +132,8 @@ async function buildDevResumeData(projectPath) {
     artifacts_consumed: artifactsConsumed,
     code_map_paths: extractCodeMapPaths(dossierRaw),
     sheldon_plan: sheldonPlan,
-    next_step: devStateNext || deriveNextStepFromPlan(planRaw)
+    next_step: devStateNext || deriveNextStepFromPlan(planRaw),
+    decision_rationale: decisionRationale.length > 0 ? decisionRationale : undefined
   };
 }
 

package/src/lib/tool-capabilities.js

@@ -5,10 +5,11 @@
 // "continue last conversation" is achieved by passing the right resume flag
 // at spawn time — AIOSON never has to track an internal session ID.
 //
-// Used by:
-//   - `aioson live:start --resume[=last|<id>]` to map to the correct argv
-//   - `aioson tool:capabilities` to expose this map as JSON to UI clients
-//     (e.g. AIOSON Play) so they don't duplicate the lookup.
+// Used by:
+//   - `aioson live:start --resume[=last|<id>]` to map to the correct argv
+//   - `aioson live:start --permission-mode=yolo` to map to the correct argv
+//   - `aioson tool:capabilities` to expose this map as JSON to UI clients
+//     (e.g. AIOSON Play) so they don't duplicate the lookup.
 //
 // Keep entries minimal and source-of-truth here. Adding a new CLI = one entry.
 const TOOL_CAPS = {
@@ -17,42 +18,50 @@ const TOOL_CAPS = {
     binary: 'claude',
     supports_resume: true,
     resume_last: ['--continue'],
-    supports_session_id: true,
-    resume_session_id: ['--resume', '<id>'],
-    supports_session_picker: true,
-    session_picker: ['--resume'],
-  },
-  codex: {
+    supports_session_id: true,
+    resume_session_id: ['--resume', '<id>'],
+    supports_session_picker: true,
+    session_picker: ['--resume'],
+    supports_yolo: true,
+    yolo_args: ['--dangerously-skip-permissions'],
+  },
+  codex: {
     install_command: 'npm install -g @openai/codex',
     binary: 'codex',
     supports_resume: true,
     resume_last: ['resume', '--last'],
-    supports_session_id: true,
-    resume_session_id: ['resume', '<id>'],
-    supports_session_picker: true,
-    session_picker: ['resume'],
-  },
-  opencode: {
+    supports_session_id: true,
+    resume_session_id: ['resume', '<id>'],
+    supports_session_picker: true,
+    session_picker: ['resume'],
+    supports_yolo: true,
+    yolo_args: ['--dangerously-bypass-approvals-and-sandbox'],
+  },
+  opencode: {
     install_command: 'npm install -g opencode-ai',
     binary: 'opencode',
     supports_resume: true,
     resume_last: ['--continue'],
-    supports_session_id: true,
-    resume_session_id: ['--session', '<id>'],
-    supports_session_picker: false,
-    session_picker: null,
-  },
-  gemini: {
+    supports_session_id: true,
+    resume_session_id: ['--session', '<id>'],
+    supports_session_picker: false,
+    session_picker: null,
+    supports_yolo: false,
+    yolo_args: null,
+  },
+  gemini: {
     install_command: 'npm install -g @google/gemini-cli',
     binary: 'gemini',
     supports_resume: false,
     resume_last: null,
-    supports_session_id: false,
-    resume_session_id: null,
-    supports_session_picker: false,
-    session_picker: null,
-  },
-};
+    supports_session_id: false,
+    resume_session_id: null,
+    supports_session_picker: false,
+    session_picker: null,
+    supports_yolo: false,
+    yolo_args: null,
+  },
+};
 
 function getToolCapabilities(tool) {
   const key = String(tool || '').trim().toLowerCase();
@@ -71,7 +80,7 @@ function listSupportedTools() {
 //   - '' / undefined / null / false → no resume
 //   - any other string → treat as session id
 // Returns [] when the tool doesn't support resume or resumeOpt is falsy.
-function resolveResumeArgs(tool, resumeOpt) {
+function resolveResumeArgs(tool, resumeOpt) {
   if (resumeOpt === undefined || resumeOpt === null || resumeOpt === '' || resumeOpt === false) {
     return [];
   }
@@ -92,11 +101,29 @@ function resolveResumeArgs(tool, resumeOpt) {
   }
 
   return Array.isArray(caps.resume_last) ? [...caps.resume_last] : [];
-}
-
-module.exports = {
-  TOOL_CAPS,
-  getToolCapabilities,
-  listSupportedTools,
-  resolveResumeArgs,
-};
+}
+
+function resolvePermissionModeArgs(tool, permissionMode) {
+  const mode = String(permissionMode || '').trim().toLowerCase();
+  if (!mode || mode === 'default') return [];
+  if (mode !== 'yolo') {
+    throw new Error(`permission_mode_unknown:${permissionMode}`);
+  }
+
+  const caps = getToolCapabilities(tool);
+  if (!caps) {
+    throw new Error(`tool_unknown:${tool}`);
+  }
+  if (!caps.supports_yolo || !Array.isArray(caps.yolo_args)) {
+    throw new Error(`permission_mode_unsupported:${tool}:yolo`);
+  }
+  return [...caps.yolo_args];
+}
+
+module.exports = {
+  TOOL_CAPS,
+  getToolCapabilities,
+  listSupportedTools,
+  resolveResumeArgs,
+  resolvePermissionModeArgs,
+};

package/src/operator-memory/decision.js

@@ -81,7 +81,7 @@ function deriveTitle(proposal) {
 function serializeDecision(data) {
   const body = String(data.body || data.proposal || '').slice(0, MAX_BODY_CHARS);
   const title = deriveTitle(data.title || data.proposal);
-  return [
+  const lines = [
     '---',
     `slug: ${data.slug}`,
     `signal_type: ${data.signal_type}`,
@@ -93,8 +93,13 @@ function serializeDecision(data) {
     `source_agent: ${data.source_agent}`,
     `quotes:${quotesToYaml(data.quotes)}`,
     `version_schema: "${SCHEMA_VERSION}"`,
-    `deprecated_by: ${data.deprecated_by ?? 'null'}`,
-    '---',
+    `deprecated_by: ${data.deprecated_by ?? 'null'}`
+  ];
+  if (data.feature_slug) lines.push(`feature_slug: ${escapeYamlString(data.feature_slug)}`);
+  if (data.session_id) lines.push(`session_id: ${escapeYamlString(data.session_id)}`);
+  lines.push('---');
+  return [
+    ...lines,
     '',
     `# ${title}`,
     '',
@@ -178,7 +183,9 @@ function promoteProposal({ identity, proposal: proposalData }) {
     quotes: proposalData.quotes || [],
     body,
     title: proposalData.proposal,
-    deprecated_by: null
+    deprecated_by: null,
+    feature_slug: proposalData.feature_slug || null,
+    session_id: proposalData.session_id || null
   };
 
   const decFilePath = decisionPath(identity, decision.slug);

package/src/operator-memory/proposal.js

@@ -46,7 +46,7 @@ function quotesToYaml(quotes) {
 }
 
 function serializeProposal(data) {
-  return [
+  const lines = [
     '---',
     `slug: ${data.slug}`,
     `signal_type: ${data.signal_type}`,
@@ -56,10 +56,12 @@ function serializeProposal(data) {
     `quotes:${quotesToYaml(data.quotes)}`,
     `proposal: ${escapeYamlString(data.proposal)}`,
     `source_agent: ${data.source_agent}`,
-    `proposal_fingerprint: ${data.proposal_fingerprint}`,
-    '---',
-    ''
-  ].join('\n');
+    `proposal_fingerprint: ${data.proposal_fingerprint}`
+  ];
+  if (data.feature_slug) lines.push(`feature_slug: ${escapeYamlString(data.feature_slug)}`);
+  if (data.session_id) lines.push(`session_id: ${escapeYamlString(data.session_id)}`);
+  lines.push('---', '');
+  return lines.join('\n');
 }
 
 function parseProposalFrontmatter(content) {
@@ -130,7 +132,7 @@ function deleteProposal(identity, slug) {
   return false;
 }
 
-function captureSignal({ identity, slug, signal_type, quote, proposal, source_agent }) {
+function captureSignal({ identity, slug, signal_type, quote, proposal, source_agent, feature_slug, session_id }) {
   if (!VALID_SIGNAL_TYPES.includes(signal_type)) {
     throw new Error(`Invalid signal_type '${signal_type}'. Must be one of: ${VALID_SIGNAL_TYPES.join(', ')}`);
   }
@@ -160,7 +162,9 @@ function captureSignal({ identity, slug, signal_type, quote, proposal, source_ag
     quotes: quote ? [String(quote).trim()].filter(Boolean) : [],
     proposal,
     source_agent: source_agent || 'unknown',
-    proposal_fingerprint: fingerprintProposal(proposal)
+    proposal_fingerprint: fingerprintProposal(proposal),
+    feature_slug: feature_slug || null,
+    session_id: session_id || null
   };
   writeProposal(identity, fresh);
   return { proposal: fresh, isNew: true };

package/src/session-handoff.js

@@ -6,6 +6,8 @@ const { exists, ensureDir } = require('./utils');
 
 const HANDOFF_RELATIVE_PATH = '.aioson/context/last-handoff.json';
 const HANDOFF_PROTOCOL_RELATIVE_PATH = '.aioson/context/handoff-protocol.json';
+const CONFIRMATIONS_JSONL = '.aioson/runtime/session-confirmations.jsonl';
+const DECISION_RATIONALE_MAX = 5;
 
 // handoff-protocol.json schema_version for `artifact_uris`:
 // v1 (legacy) — array of strings; v2 — array of {path, kind, agent, added_at}.
@@ -63,10 +65,52 @@ function coerceArtifactUris(uris, fallbackAgent) {
     .filter(Boolean);
 }
 
+async function collectDecisionRationale(targetDir) {
+  const accPath = path.join(targetDir, CONFIRMATIONS_JSONL);
+  try {
+    const raw = await fs.readFile(accPath, 'utf8');
+    const lines = raw.trim().split('\n').filter(Boolean);
+    const entries = [];
+    for (const line of lines) {
+      try {
+        const obj = JSON.parse(line);
+        entries.push({
+          agent: obj.agent || 'unknown',
+          decision: obj.decision || '',
+          alternatives_considered: null,
+          rationale: obj.quote || null,
+          confidence: 'confirmed'
+        });
+      } catch {
+        // skip malformed lines
+      }
+    }
+    // BR-AO-04: FIFO — keep only the last N entries
+    return entries.slice(-DECISION_RATIONALE_MAX);
+  } catch {
+    return [];
+  }
+}
+
+async function clearConfirmationsAccumulator(targetDir) {
+  const accPath = path.join(targetDir, CONFIRMATIONS_JSONL);
+  try {
+    await fs.unlink(accPath);
+  } catch {
+    // file may not exist
+  }
+}
+
 async function writeHandoff(targetDir, payload) {
   const handoffPath = path.join(targetDir, HANDOFF_RELATIVE_PATH);
   const protocolPath = path.join(targetDir, HANDOFF_PROTOCOL_RELATIVE_PATH);
   await ensureDir(path.dirname(handoffPath));
+
+  // M2: collect decision rationale from session confirmations
+  const sessionRationale = await collectDecisionRationale(targetDir);
+  const existingRationale = Array.isArray(payload.decisionRationale) ? payload.decisionRationale : [];
+  const mergedRationale = [...existingRationale, ...sessionRationale].slice(-DECISION_RATIONALE_MAX);
+
   const handoff = {
     version: 1,
     session_ended_at: new Date().toISOString(),
@@ -79,10 +123,14 @@ async function writeHandoff(targetDir, payload) {
     context_files_updated: Array.isArray(payload.contextFilesUpdated) ? payload.contextFilesUpdated : [],
     workflow_mode: payload.workflowMode || null,
     classification: payload.classification || null,
-    feature_slug: payload.featureSlug || null
+    feature_slug: payload.featureSlug || null,
+    decision_rationale: mergedRationale.length > 0 ? mergedRationale : undefined
   };
   await fs.writeFile(handoffPath, `${JSON.stringify(handoff, null, 2)}\n`, 'utf8');
 
+  // Clear accumulator after writing to handoff
+  await clearConfirmationsAccumulator(targetDir);
+
   const protocol = payload.protocol || buildBasicHandoffProtocol(payload);
   await fs.writeFile(protocolPath, `${JSON.stringify(protocol, null, 2)}\n`, 'utf8');
 
@@ -283,9 +331,12 @@ function buildRuntimeLogHandoff(agentName, message, summary) {
 module.exports = {
   HANDOFF_RELATIVE_PATH,
   HANDOFF_PROTOCOL_RELATIVE_PATH,
+  CONFIRMATIONS_JSONL,
+  DECISION_RATIONALE_MAX,
   ARTIFACT_KINDS,
   coerceArtifactUri,
   coerceArtifactUris,
+  collectDecisionRationale,
   writeHandoff,
   readHandoff,
   readHandoffProtocol,

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

@@ -34,6 +34,8 @@ 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
 ```
 
 For feature mode with existing requirements, run before the synchronization gate:
@@ -341,5 +343,35 @@ aioson dev:state:write . --feature={slug} --phase=1 \
 
 `--context` accepts canonical tokens (`prd`, `requirements`, `spec`, `architecture`, `impl-plan`, `sheldon`, `design-doc`, `dossier`), 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.
 
+**Handoff message:**
+```
+Requirements written: .aioson/context/requirements-{slug}.md
+Spec skeleton: .aioson/context/spec-{slug}.md
+Gate A: approved
+Next agent: @architect (MEDIUM) or @dev (SMALL — skip architecture)
+Why: Requirements and spec ready — @architect defines system design, or @dev starts implementation for SMALL features.
+Action: /architect or /dev
+```
+> Recommended: `/clear` before activating — fresh context window.
+
+## Strategic commands (use during session)
+
+- Search memory before web research: `aioson memory:search . --query="<topic>" 2>/dev/null || true`
+- Search context files: `aioson context:search . --query="<term>" 2>/dev/null || true`
+- Compress context before handoff: `aioson context:pack . 2>/dev/null || true`
+- Create spec checkpoint before changes: `aioson spec:checkpoint . --feature={slug} 2>/dev/null || true`
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=analyst --summary="Discovery <slug>: <N> entities, <N> rules" 2>/dev/null || true`
+
+At strategic milestones during execution, emit progress signals:
+```bash
+aioson runtime:emit . --agent=analyst --type=milestone --summary="Requirements written: {slug}, {N} BRs, {N} ECs" 2>/dev/null || true
+aioson runtime:emit . --agent=analyst --type=milestone --summary="Spec skeleton created: {slug}" 2>/dev/null || true
+```
+
+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
+```

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

@@ -124,6 +124,20 @@ Before handing off to `@dev`:
 - If a relevant spec file exists and design is still pending, do not claim Gate B passed.
 - Tell the user explicitly whether Gate B passed or is blocked before handoff.
 
+When Gate B passes, register it via CLI:
+```bash
+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.
+
 ## Rules
 - Do not redesign entities produced by `@analyst`. Consume the data design as-is.
 - Keep architecture proportional to classification. Never apply MEDIUM patterns to a MICRO project.
@@ -321,5 +335,23 @@ Keep architecture.md proportional — verbose output costs tokens without adding
 - Do not introduce patterns that do not exist in the chosen stack's conventions.
 - Do not copy content from discovery.md into architecture.md. Reference sections by name: "see discovery.md § Entities". The document chain is already in context.
 
+## Strategic commands (use during session)
+
+- Search context for existing decisions: `aioson context:search . --query="<architectural term>" 2>/dev/null || true`
+- Validate artifacts against spec: `aioson artifact:validate . --feature={slug} 2>/dev/null || true`
+- Compress context before handoff: `aioson context:pack . 2>/dev/null || true`
+- Audit dossier completeness: `aioson dossier:audit . --check=coverage 2>/dev/null || true`
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=architect --summary="Architecture <slug>: <stack>, <N> modules" 2>/dev/null || true`
+
+At strategic milestones during execution, emit progress signals:
+```bash
+aioson runtime:emit . --agent=architect --type=milestone --summary="Architecture decided: {slug}, {stack}" 2>/dev/null || true
+aioson runtime:emit . --agent=architect --type=gate_check --summary="Gate B: {approved|blocked} for {slug}" 2>/dev/null || true
+```
+
+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
+```

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

@@ -92,6 +92,16 @@ Wait for confirmation.
 Write `.aioson/briefings/{slug}/briefings.md` and update `.aioson/briefings/config.md`.
 See **Output contract** below for exact formats.
 
+After writing the briefing draft, emit a milestone:
+```bash
+aioson runtime:emit . --agent=briefing --type=milestone --summary="Briefing draft written: {slug}" 2>/dev/null || true
+```
+
+If a feature dossier exists for the target slug, record the briefing:
+```bash
+aioson dossier:add-finding . --slug={slug} --agent=briefing --section="Agent Trail" --content="Briefing created: {N} themes, {N} risks, {N} open questions" 2>/dev/null || true
+```
+
 ## Mode: Conversational (no plans)
 
 When `plans/` is empty or the user wants to plan via conversation:
@@ -222,12 +232,24 @@ Always register additional files with a note at the bottom of `briefings.md`:
 - `{specific-theme}.md` — {one line description}
 ```
 
+## Feature dossier
+
+Check `.aioson/context/features/{slug}/dossier.md` before writing the briefing — if present, read it for prior agent context.
+
+**After writing the briefing**, record in the dossier:
+```
+aioson dossier:add-finding . --slug={slug} --agent=briefing --section="Agent Trail" --content="Briefing created: {N} themes, {N} risks, {N} open questions" 2>/dev/null || true
+```
+
+Skip silently when the dossier is absent.
+
 ## Rules
 
 - **Never modify `plans/`** — they are read-only. Plans belong to the user.
 - **Never access `.aioson/briefings/` from @dev** — briefings are pre-production. @dev receives the PRD already built.
 - **Never create a PRD** — that is `@product`'s responsibility.
 - **Never approve a briefing automatically** — approval requires explicit user action via CLI.
+- When a briefing is approved (via CLI), emit: `aioson runtime:emit . --agent=briefing --type=milestone --summary="Briefing approved: {slug}" 2>/dev/null || true`
 - **Never overwrite an existing briefing** without confirming with the user first.
 - **Slug must be confirmed** by the user before any file is written.
 - **Never recommend `@sheldon` (or any post-PRD agent) as the next step.** The only handoff from `@briefing` is `@product`. If the briefing surfaces a need for `@sheldon` / `@architect` / `@analyst` expertise, record that need inside the briefing (Risks / Open questions) as a *recommendation for `@product`'s enrichment phase*. `@product` decides when to invoke specialists after the PRD exists. See `briefing-craft.md` §1 "Mitigating weak markers" for examples.
@@ -252,6 +274,7 @@ Always register additional files with a note at the bottom of `briefings.md`:
 - `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`.