@jaimevalasek/aioson 1.17.2 → 1.18.0

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

@@ -217,7 +217,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:
@@ -1116,10 +1116,11 @@ module.exports = {
     plan_not_found: 'Arquivo de plano nao encontrado: {plan}',
     no_active_session: 'Nenhuma sessao live ativa encontrada para {agent}.',
     session_not_active: 'A sessao live de {agent} nao esta ativa.',
-    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.',
-    micro_task_already_open: 'Uma micro-tarefa live ja esta aberta para {agent}. Emita task_completed antes de task_started novamente.',
+    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}.',
     watch_json_conflict: '--watch nao pode ser combinado com --json.',

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:
@@ -331,7 +333,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 `/dev` session auto-resumes on cold start instead of pinging the user for context:
+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:
 
 ```bash
 aioson dev:state:write . --feature={slug} --phase=1 \
@@ -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

@@ -66,6 +66,7 @@ After the user selects which plans to use:
 - Read each selected `plans/*.md` file fully.
 - Read `project.context.md` for project context.
 - 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**
 
@@ -91,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:
@@ -221,14 +232,27 @@ 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.
 - Use `interaction_language` (fallback: `conversation_language`) from `project.context.md` for all interaction and output.
 
 ## Responsibility boundary
@@ -250,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`.
 
@@ -259,6 +284,6 @@ Always register additional files with a note at the bottom of `briefings.md`:
 ```bash
 aioson briefing:approve   # mark as approved
 ```
-Then: activate `/product` — it will detect the approved briefing automatically.
+Then: activate `/aioson:agent:product` — it will detect the approved briefing automatically.
 > Recommended: `/clear` first — fresh context window
 ---

package/template/.aioson/agents/copywriter.md

@@ -25,7 +25,7 @@ understood, eliminates objections, and drives one clear action.
 ## When to activate
 
 @copywriter can be invoked:
-- **Standalone:** `/copywriter` or `@copywriter <context>` — write copy for a page, campaign, or feature
+- **Standalone:** `/aioson:agent:copywriter` or `@copywriter <context>` — write copy for a page, campaign, or feature
 - **From @ux-ui:** automatically when `project_type=site` and copy is missing (copy gate)
 - **From @squad:** squad executors can route copy requests here
 - **From @squad executor:** a copywriter squad executor is a specialization of this agent

package/template/.aioson/agents/dev.md

@@ -34,7 +34,7 @@ Use output to orient; load listed `rules`/`design_governance` before structural
 
 **Step 0.1 — Bootstrap gate (Living Memory):** read `aioson memory:status .` output. If `Bootstrap < 4/4` or the bootstrap files are older than 30 days, emit a warning at the top of your response:
 
-> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Run `/discover` (or `aioson memory:refresh`) before continuing on broad work.
+> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Run `/aioson:agent:discover` (or `aioson memory:refresh`) before continuing on broad work.
 
 This is advisory — proceed with the user's task, but the warning surfaces the gap so the next session can fix it. Skip when bootstrap/ does not exist (greenfield).
 
@@ -264,7 +264,7 @@ Run `aioson` CLI yourself to keep the workflow moving:
 
 ## Auto-cycle return to @qa (corrections mode)
 
-If `.aioson/runtime/qa-dev-cycle.json` exists and its `slug` matches the active feature, you're in an auto-correction cycle started by `@qa`. After applying the plan in `last_plan` and tests pass: (1) update dossier + spec, (2) mark plan `status: resolved`, (3) auto-invoke `Skill(aioson:qa)` with `"re-verify after applying <plan path>"`. No user prompt — Ctrl+C interrupts. If the file is absent or slug differs, manual handoff as before.
+If `.aioson/runtime/qa-dev-cycle.json` exists and its `slug` matches the active feature, you're in an auto-correction cycle started by `@qa`. After applying the plan in `last_plan` and tests pass: (1) update dossier + spec, (2) mark plan `status: resolved`, (3) auto-invoke `Skill(aioson:agent:qa)` with `"re-verify after applying <plan path>"`. No user prompt — Ctrl+C interrupts. If the file is absent or slug differs, manual handoff as before.
 
 ## Security findings consumption
 

package/template/.aioson/agents/deyvin.md

@@ -7,14 +7,14 @@ Act as the continuity-first pair programming agent for AIOSON. Your codename is
 
 **Bootstrap gate (Living Memory) — MANDATORY first action:**
 
-Before any other action on `/deyvin` activation, check Living Memory coverage:
+Before any other action on `/aioson:agent:deyvin` activation, check Living Memory coverage:
 
 1. **If `aioson` CLI is available**: run `aioson memory:status .` and read the output.
 2. **If `aioson` CLI is not available**: read `.aioson/context/bootstrap/*.md` directly via filesystem. Count present files (max 4: `what-is.md`, `what-it-does.md`, `how-it-works.md`, `current-state.md`) and the oldest modification date.
 
 If `Bootstrap < 4/4` OR files are older than 30 days, prefix your first reply with:
 
-> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Recommend `/discover` (or `aioson memory:refresh`) before broad work.
+> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Recommend `/aioson:agent:discover` (or `aioson memory:refresh`) before broad work.
 
 This is advisory — continue with the user's task. Skip the gate only when `.aioson/context/bootstrap/` does not exist (greenfield project).
 
@@ -110,14 +110,14 @@ Apply this table deterministically after reading the user's request and consulti
 | Small slice of well-bounded code change; code already partially understood | Handle here (pair execution) |
 | Bug fix with failing test attached, or clear error message + reproducer | Handle here via `debugging-escalation.md` |
 | Diagnosis ambiguous; needs survey of >5 files or tracing a runtime flow | **Spawn sub-task scout** via `aioson scout:prep` (or CLI-less fallback — see "Sub-task scout invocation" below) |
-| New feature, new module, or cross-product surface | Handoff `/product` |
-| Decision affects multiple modules / system-wide architecture | Handoff `/architect` |
-| Missing domain rules, entities, or brownfield knowledge gap | Handoff `/analyst` |
-| PRD exists for the feature but is thin / sized wrong | Handoff `/sheldon` |
-| Visual direction unclear or UI system not defined | Handoff `/ux-ui` |
-| Vague scope, unclear readiness, contradictions | Handoff `/discovery-design-doc` |
-| Larger structured implementation batch that no longer fits pair conversation | Handoff `/dev` |
-| Formal QA / risk review or test pass requested | Handoff `/qa` |
+| New feature, new module, or cross-product surface | Handoff `/aioson:agent:product` |
+| Decision affects multiple modules / system-wide architecture | Handoff `/aioson:agent:architect` |
+| Missing domain rules, entities, or brownfield knowledge gap | Handoff `/aioson:agent:analyst` |
+| PRD exists for the feature but is thin / sized wrong | Handoff `/aioson:agent:sheldon` |
+| Visual direction unclear or UI system not defined | Handoff `/aioson:agent:ux-ui` |
+| Vague scope, unclear readiness, contradictions | Handoff `/aioson:agent:discovery-design-doc` |
+| Larger structured implementation batch that no longer fits pair conversation | Handoff `/aioson:agent:dev` |
+| Formal QA / risk review or test pass requested | Handoff `/aioson:agent:qa` |
 
 **Tie-breakers when two rows apply:**
 1. If the request is ambiguous, escalate (handoff) instead of handling.
@@ -136,7 +136,7 @@ When the rubric routes here ("Diagnosis ambiguous; needs survey of >5 files or t
    - **Claude Code**: Agent tool with `tools: [Read, Grep]`, `disallowedTools: [Bash, Edit, Write]`, `prompt = <returned string>`. Sub-agent writes JSON to the returned `output_path`.
    - **Codex MultiAgentV2**: spawn subagent with the prompt; collect JSON from `output_path`.
    - **Other harnesses lacking isolated sub-agent**: use the CLI-less fallback below.
-4. `aioson scout:validate . --json --input=<output_path>`. On `schema_invalid`, re-prompt the sub-agent with `error.details`. On `retry_exhausted`, surface to user and offer manual `/architect` or `/dev` handoff.
+4. `aioson scout:validate . --json --input=<output_path>`. On `schema_invalid`, re-prompt the sub-agent with `error.details`. On `retry_exhausted`, surface to user and offer manual `/aioson:agent:architect` or `/aioson:agent:dev` handoff.
 5. `aioson scout:commit . --json --input=<output_path>` — telemetry emitted, cap counter decremented.
 6. Read `findings`/`recommendation` from the persisted JSON; fold into your reply. Parent context grew ~500 tokens (the report) instead of 5000+ (the surveyed files).
 
@@ -172,7 +172,7 @@ Dispatch via harness sub-agent with the tool whitelist `[Read, Grep]`. Read the
 
 ### Cap discipline (both paths)
 
-- Default: max **3 scouts per parent session**. If you've dispatched 3 and still need more, the rubric's next row applies — handoff to `/architect`.
+- Default: max **3 scouts per parent session**. If you've dispatched 3 and still need more, the rubric's next row applies — handoff to `/aioson:agent:architect`.
 - Default: max **20 files per scout scope**. If a survey naturally needs more, split into two scouts with disjoint scopes.
 - Defaults are tunable in `.aioson/config/scout-engine.json`.