@jaimevalasek/aioson 1.5.1 → 1.6.0

package/src/recovery-context-session.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+
+const execFileAsync = promisify(execFile);
+
+const CONTEXT_DIR = path.join('.aioson', 'context');
+const RECOVERY_FILE = 'recovery-context.md';
+const MAX_TOKENS = 2000;
+
+function estimateTokens(str) {
+  return Math.ceil(str.length / 4);
+}
+
+async function readRecentGitLog(cwd, limit = 10) {
+  try {
+    const { stdout } = await execFileAsync('git', [
+      'log', `--max-count=${limit}`, '--oneline', '--no-merges'
+    ], { cwd });
+    return stdout.trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+async function readModifiedFiles(cwd) {
+  try {
+    const { stdout } = await execFileAsync('git', [
+      'diff', '--name-only', 'HEAD'
+    ], { cwd });
+    return stdout.trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function buildSessionRecoveryMarkdown(sessionState, gitLog, modifiedFiles) {
+  const lines = [];
+
+  lines.push('# Recovery Context — Direct Session');
+  lines.push(`> Generated: ${new Date().toISOString()}`);
+  lines.push('');
+
+  // Session goal/task
+  if (sessionState.goal) {
+    lines.push('## Current Goal');
+    lines.push(sessionState.goal);
+    lines.push('');
+  }
+
+  // Active agent
+  if (sessionState.agent) {
+    lines.push('## Active Agent');
+    lines.push(sessionState.agent);
+    lines.push('');
+  }
+
+  // Tasks
+  const tasks = Array.isArray(sessionState.tasks) ? sessionState.tasks : [];
+  if (tasks.length > 0) {
+    lines.push('## Tasks');
+    for (const t of tasks.slice(-5)) {
+      const status = t.status || 'unknown';
+      const title = t.title || t.id || '(untitled)';
+      lines.push(`- [${status}] ${title}`);
+    }
+    lines.push('');
+  }
+
+  // Notes
+  const notes = Array.isArray(sessionState.notes) ? sessionState.notes : [];
+  if (notes.length > 0) {
+    lines.push('## Notes');
+    for (const note of notes.slice(-5)) {
+      lines.push(`- ${note}`);
+    }
+    lines.push('');
+  }
+
+  // Modified files
+  if (modifiedFiles.length > 0) {
+    lines.push('## Modified Files');
+    for (const f of modifiedFiles.slice(0, 10)) {
+      lines.push(`- ${f}`);
+    }
+    lines.push('');
+  }
+
+  // Recent git commits
+  if (gitLog.length > 0) {
+    lines.push('## Recent Commits');
+    for (const entry of gitLog.slice(0, 5)) {
+      lines.push(`- ${entry}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('*Inject this file at the top of your next session to restore context after a compact.*');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate and write recovery-context.md for a direct session (no squad).
+ * @param {string} cwd  — project root directory
+ * @param {object} sessionState  — { goal?, agent?, tasks?, notes? }
+ * @returns {{ ok: boolean, path: string, tokens: number }}
+ */
+async function generateSessionRecovery(cwd, sessionState = {}) {
+  const [gitLog, modifiedFiles] = await Promise.all([
+    readRecentGitLog(cwd),
+    readModifiedFiles(cwd)
+  ]);
+
+  let content = buildSessionRecoveryMarkdown(sessionState, gitLog, modifiedFiles);
+
+  // Enforce token budget
+  if (estimateTokens(content) > MAX_TOKENS) {
+    content = buildSessionRecoveryMarkdown(sessionState, gitLog.slice(0, 3), modifiedFiles.slice(0, 5));
+  }
+
+  const tokens = estimateTokens(content);
+  const outDir = path.join(cwd, CONTEXT_DIR);
+  const outPath = path.join(outDir, RECOVERY_FILE);
+
+  try {
+    await fs.mkdir(outDir, { recursive: true });
+    await fs.writeFile(outPath, content, 'utf8');
+  } catch (err) {
+    return { ok: false, error: err.message, path: outPath, tokens };
+  }
+
+  return { ok: true, path: outPath, tokens };
+}
+
+/**
+ * Read the current session recovery-context.md (returns null if missing).
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+async function readSessionRecovery(cwd) {
+  const p = path.join(cwd, CONTEXT_DIR, RECOVERY_FILE);
+  try {
+    return await fs.readFile(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { generateSessionRecovery, readSessionRecovery };

package/src/runtime-store.js

@@ -693,6 +693,34 @@ function ensureLegacyColumns(db) {
   }
 
   try { db.exec('ALTER TABLE worker_runs ADD COLUMN conversation_id TEXT'); } catch { /* já existe */ }
+
+  // Dynamic Tools (Feature: Tool Registry)
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS dynamic_tools (
+      name TEXT PRIMARY KEY,
+      description TEXT NOT NULL,
+      input_schema TEXT NOT NULL DEFAULT '{}',
+      handler_type TEXT NOT NULL DEFAULT 'shell',
+      handler_code TEXT,
+      handler_path TEXT,
+      squad_slug TEXT,
+      registered_at TEXT NOT NULL DEFAULT (datetime('now')),
+      registered_by TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_dynamic_tools_squad ON dynamic_tools(squad_slug);
+  `);
+
+  // Evolution Log (Feature: Learning Evolution Pipeline)
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS evolution_log (
+      id TEXT PRIMARY KEY,
+      applied_at TEXT NOT NULL,
+      deltas_count INTEGER NOT NULL DEFAULT 0,
+      squad_slug TEXT,
+      files_json TEXT,
+      source_learning_ids_json TEXT
+    );
+  `);
 }
 
 function insertEvent(db, record) {
@@ -2425,6 +2453,66 @@ function deleteROIConfig(db, squadSlug) {
   return db.prepare('DELETE FROM squad_roi_config WHERE squad_slug = ?').run(squadSlug);
 }
 
+// ─── Dynamic Tools CRUD ───────────────────────────────────────────────────────
+
+function registerDynamicTool(db, opts) {
+  const now = nowIso();
+  db.prepare(`
+    INSERT OR REPLACE INTO dynamic_tools
+      (name, description, input_schema, handler_type, handler_code, handler_path, squad_slug, registered_at, registered_by)
+    VALUES
+      (@name, @description, @inputSchema, @handlerType, @handlerCode, @handlerPath, @squadSlug, @registeredAt, @registeredBy)
+  `).run({
+    name: String(opts.name),
+    description: String(opts.description),
+    inputSchema: opts.inputSchema ? JSON.stringify(opts.inputSchema) : '{}',
+    handlerType: String(opts.handlerType || 'shell'),
+    handlerCode: opts.handlerCode || null,
+    handlerPath: opts.handlerPath || null,
+    squadSlug: opts.squadSlug || null,
+    registeredAt: now,
+    registeredBy: opts.registeredBy || null
+  });
+  return opts.name;
+}
+
+function unregisterDynamicTool(db, name) {
+  return db.prepare('DELETE FROM dynamic_tools WHERE name = ?').run(name);
+}
+
+function getDynamicTool(db, name) {
+  return db.prepare('SELECT * FROM dynamic_tools WHERE name = ?').get(name) || null;
+}
+
+function listDynamicTools(db, squadSlug = null) {
+  if (squadSlug) {
+    return db.prepare('SELECT * FROM dynamic_tools WHERE squad_slug = ? ORDER BY registered_at DESC').all(squadSlug);
+  }
+  return db.prepare('SELECT * FROM dynamic_tools ORDER BY registered_at DESC').all();
+}
+
+// ─── Evolution Log CRUD ───────────────────────────────────────────────────────
+
+function insertEvolutionLog(db, opts) {
+  const id = `evo-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+  db.prepare(`
+    INSERT INTO evolution_log (id, applied_at, deltas_count, squad_slug, files_json, source_learning_ids_json)
+    VALUES (@id, @appliedAt, @deltasCount, @squadSlug, @filesJson, @sourceIdsJson)
+  `).run({
+    id,
+    appliedAt: nowIso(),
+    deltasCount: Number(opts.deltasCount || 0),
+    squadSlug: opts.squadSlug || null,
+    filesJson: JSON.stringify(opts.files || []),
+    sourceIdsJson: JSON.stringify(opts.sourceLearningIds || [])
+  });
+  return id;
+}
+
+function listEvolutionLog(db, limit = 20) {
+  return db.prepare('SELECT * FROM evolution_log ORDER BY applied_at DESC LIMIT ?').all(limit);
+}
+
 module.exports = {
   resolveRuntimePaths,
   runtimeStoreExists,
@@ -2518,5 +2606,13 @@ module.exports = {
   // ROI Config CRUD
   upsertROIConfig,
   getROIConfig,
-  deleteROIConfig
+  deleteROIConfig,
+  // Dynamic Tools CRUD
+  registerDynamicTool,
+  unregisterDynamicTool,
+  getDynamicTool,
+  listDynamicTools,
+  // Evolution Log CRUD
+  insertEvolutionLog,
+  listEvolutionLog
 };

package/src/sandbox.js

@@ -0,0 +1,177 @@
+'use strict';
+
+const { spawn } = require('node:child_process');
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_OUTPUT_BYTES = 5 * 1024; // 5KB before summarization
+
+// Credential redaction patterns — covers the most common secret formats
+const REDACTION_PATTERNS = [
+  // GitHub tokens (classic and fine-grained)
+  { pattern: /ghp_[A-Za-z0-9]{36}/g, replacement: 'ghp_[REDACTED]' },
+  { pattern: /github_pat_[A-Za-z0-9_]{82}/g, replacement: 'github_pat_[REDACTED]' },
+  // AWS access keys
+  { pattern: /AKIA[0-9A-Z]{16}/g, replacement: 'AKIA[REDACTED]' },
+  // Google OAuth tokens
+  { pattern: /ya29\.[A-Za-z0-9_\-]{50,}/g, replacement: 'ya29.[REDACTED]' },
+  // Generic Bearer tokens in headers
+  { pattern: /Bearer\s+[A-Za-z0-9\-._~+\/]+=*/gi, replacement: 'Bearer [REDACTED]' },
+  // Password in URL (e.g. postgres://user:password@host)
+  { pattern: /:[^/:@\s]{4,}@[a-z0-9.\-]+(?::\d+)?/gi, replacement: ':[REDACTED]@host' },
+  // Generic password= key=value pairs
+  { pattern: /password\s*=\s*["']?[^\s"'&;,]{4,}["']?/gi, replacement: 'password=[REDACTED]' },
+  { pattern: /passwd\s*=\s*["']?[^\s"'&;,]{4,}["']?/gi, replacement: 'passwd=[REDACTED]' },
+  // secret= key=value pairs
+  { pattern: /secret\s*=\s*["']?[^\s"'&;,]{4,}["']?/gi, replacement: 'secret=[REDACTED]' },
+  // api_key= or apikey= patterns
+  { pattern: /api[_-]?key\s*=\s*["']?[^\s"'&;,]{4,}["']?/gi, replacement: 'api_key=[REDACTED]' },
+  // Private key blocks
+  { pattern: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g, replacement: '-----BEGIN PRIVATE KEY [REDACTED] END PRIVATE KEY-----' },
+];
+
+/**
+ * Redact known credential patterns from a string.
+ * @param {string} text
+ * @returns {string}
+ */
+function redactCredentials(text) {
+  if (!text) return text;
+  let result = text;
+  for (const { pattern, replacement } of REDACTION_PATTERNS) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+/**
+ * Summarize long output to stay within size budget.
+ * @param {string} output
+ * @param {string} intent — optional context about what was executed
+ * @param {number} maxSize — max bytes to return
+ * @returns {string}
+ */
+function summarizeOutput(output, intent = '', maxSize = MAX_OUTPUT_BYTES) {
+  if (!output || output.length <= maxSize) return output;
+
+  const half = Math.floor(maxSize / 2);
+  const head = output.slice(0, half);
+  const tail = output.slice(-half);
+  const omitted = output.length - maxSize;
+  const intentNote = intent ? ` (${intent})` : '';
+
+  return `${head}\n\n[... ${omitted} bytes omitted${intentNote} ...]\n\n${tail}`;
+}
+
+/**
+ * Execute a shell command in a sandboxed subprocess with timeout and redaction.
+ *
+ * @param {string} command  — shell command to run
+ * @param {object} opts     — { cwd?, timeout?, env?, maxOutput?, intent?, shell? }
+ * @returns {{ ok: boolean, stdout: string, stderr: string, exitCode: number|null, timedOut: boolean }}
+ */
+async function executeInSandbox(command, opts = {}) {
+  const timeout = opts.timeout || DEFAULT_TIMEOUT_MS;
+  const cwd = opts.cwd || process.cwd();
+  const maxOutput = opts.maxOutput || MAX_OUTPUT_BYTES;
+  const intent = opts.intent || command.slice(0, 60);
+  const shell = opts.shell !== false; // default true
+
+  return new Promise((resolve) => {
+    const controller = new AbortController();
+    let timedOut = false;
+    let killed = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeout);
+
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutSize = 0;
+    let stderrSize = 0;
+
+    const baseOpts = {
+      cwd,
+      env: { ...process.env, ...(opts.env || {}) },
+      signal: controller.signal
+    };
+
+    let child;
+    try {
+      if (shell) {
+        // Use Node's built-in shell wrapping
+        child = spawn(command, [], { ...baseOpts, shell: true });
+      } else {
+        const parts = command.split(/\s+/);
+        child = spawn(parts[0], parts.slice(1), { ...baseOpts, shell: false });
+      }
+    } catch (err) {
+      clearTimeout(timer);
+      resolve({ ok: false, stdout: '', stderr: err.message, exitCode: null, timedOut: false, error: err.message });
+      return;
+    }
+
+    child.stdout.on('data', (chunk) => {
+      if (stdoutSize < maxOutput * 2) {
+        stdoutChunks.push(chunk);
+        stdoutSize += chunk.length;
+      }
+    });
+
+    child.stderr.on('data', (chunk) => {
+      if (stderrSize < maxOutput * 2) {
+        stderrChunks.push(chunk);
+        stderrSize += chunk.length;
+      }
+    });
+
+    child.on('close', (code, signal) => {
+      if (killed) return;
+      clearTimeout(timer);
+
+      const rawStdout = Buffer.concat(stdoutChunks).toString('utf8');
+      const rawStderr = Buffer.concat(stderrChunks).toString('utf8');
+
+      const stdout = redactCredentials(summarizeOutput(rawStdout, intent, maxOutput));
+      const stderr = redactCredentials(summarizeOutput(rawStderr, intent, maxOutput));
+
+      resolve({
+        ok: !timedOut && code === 0,
+        stdout,
+        stderr,
+        exitCode: code,
+        timedOut,
+        signal: signal || null
+      });
+    });
+
+    child.on('error', (err) => {
+      if (killed) return;
+      clearTimeout(timer);
+
+      if (err.code === 'ABORT_ERR' || timedOut) {
+        resolve({
+          ok: false,
+          stdout: '',
+          stderr: `Command timed out after ${timeout}ms`,
+          exitCode: null,
+          timedOut: true,
+          signal: null
+        });
+      } else {
+        resolve({
+          ok: false,
+          stdout: '',
+          stderr: err.message,
+          exitCode: null,
+          timedOut: false,
+          error: err.message
+        });
+      }
+      killed = true;
+    });
+  });
+}
+
+module.exports = { executeInSandbox, redactCredentials, summarizeOutput };

package/src/tool-executor.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const SAFE_ENV_KEYS = new Set(['PATH', 'HOME', 'LANG', 'TERM', 'USER', 'SHELL', 'TMPDIR', 'TMP', 'TEMP']);
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+function buildSafeEnv(inputJson) {
+  const safe = {};
+  for (const key of SAFE_ENV_KEYS) {
+    if (process.env[key] !== undefined) {
+      safe[key] = process.env[key];
+    }
+  }
+  safe.TOOL_INPUT = typeof inputJson === 'string' ? inputJson : JSON.stringify(inputJson ?? {});
+  return safe;
+}
+
+/**
+ * Executa uma dynamic tool de forma segura via subprocess.
+ * @param {object} toolDef - Registro da tool (da tabela dynamic_tools)
+ * @param {object|string} inputJson - Input para a tool
+ * @param {object} opts
+ * @param {string} [opts.projectDir] - Diretório do projeto (para resolver caminhos relativos)
+ * @param {number} [opts.timeoutMs] - Timeout em ms (default: 30s)
+ * @returns {{ ok: boolean, stdout: string, stderr: string, exitCode: number, error?: string }}
+ */
+function executeTool(toolDef, inputJson, opts = {}) {
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const projectDir = opts.projectDir || process.cwd();
+  const safeEnv = buildSafeEnv(inputJson);
+
+  let result;
+
+  if (toolDef.handler_type === 'shell') {
+    if (!toolDef.handler_code) {
+      return { ok: false, stdout: '', stderr: '', exitCode: 1, error: 'handler_code is required for shell tools' };
+    }
+    result = spawnSync('bash', ['-c', toolDef.handler_code], {
+      env: safeEnv,
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      maxBuffer: 1024 * 1024
+    });
+  } else if (toolDef.handler_type === 'script') {
+    if (!toolDef.handler_path) {
+      return { ok: false, stdout: '', stderr: '', exitCode: 1, error: 'handler_path is required for script tools' };
+    }
+    const scriptPath = path.isAbsolute(toolDef.handler_path)
+      ? toolDef.handler_path
+      : path.resolve(projectDir, toolDef.handler_path);
+
+    result = spawnSync('node', ['--env-file=', scriptPath], {
+      env: safeEnv,
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      maxBuffer: 1024 * 1024,
+      input: safeEnv.TOOL_INPUT
+    });
+
+    // Fallback: node sem --env-file= (versões antigas do Node não suportam)
+    if (result.error && result.error.code === 'ERR_INVALID_ARG_VALUE') {
+      result = spawnSync('node', [scriptPath], {
+        env: safeEnv,
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        maxBuffer: 1024 * 1024,
+        input: safeEnv.TOOL_INPUT
+      });
+    }
+  } else {
+    return { ok: false, stdout: '', stderr: '', exitCode: 1, error: `Unknown handler_type: ${toolDef.handler_type}` };
+  }
+
+  const stdout = String(result.stdout || '').trim();
+  const stderr = String(result.stderr || '').trim();
+  const exitCode = result.status ?? 1;
+
+  if (result.error) {
+    const isTimeout = result.error.code === 'ETIMEDOUT' || result.error.killed;
+    return {
+      ok: false,
+      stdout,
+      stderr,
+      exitCode,
+      error: isTimeout ? `Tool timed out after ${timeoutMs}ms` : result.error.message
+    };
+  }
+
+  return { ok: exitCode === 0, stdout, stderr, exitCode };
+}
+
+module.exports = { executeTool, buildSafeEnv };

package/src/updater.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const path = require('node:path');
-const { detectExistingInstall, installTemplate } = require('./installer');
+const { detectExistingInstall, installTemplate, readInstallProfile } = require('./installer');
 
 async function updateInstallation(targetDir, options = {}) {
   const installed = await detectExistingInstall(targetDir);
@@ -13,17 +13,25 @@ async function updateInstallation(targetDir, options = {}) {
     };
   }
 
+  const savedProfile = await readInstallProfile(targetDir);
+
+  // During update, pass null profile so ALL framework files are installed
+  // (not just those matching the saved profile).
+  // This ensures new framework files from the new version are always installed.
+  // Profile-based filtering only applies to init/install.
   const result = await installTemplate(targetDir, {
     overwrite: true,
     dryRun: Boolean(options.dryRun),
     mode: 'update',
     backupOnOverwrite: true,
-    frameworkDetection: options.frameworkDetection || null
+    frameworkDetection: options.frameworkDetection || null,
+    installProfile: null
   });
 
   return {
     ok: true,
-    ...result
+    ...result,
+    savedProfile
   };
 }
 

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

@@ -40,6 +40,25 @@ Check the following before doing anything else:
 - `.aioson/context/design-doc.md` + `readiness.md` (if present)
 - `.aioson/context/discovery.md` + `spec.md` (feature mode — project context, if present)
 
+## Context loading policy
+
+**Sempre carregar:**
+- `.aioson/context/project.context.md`
+- `prd*.md` ou `prd-{slug}.md` relevante
+- `sheldon-enrichment-{slug}.md` (se existir)
+
+**Carregar só se relevante ao scope:**
+- `architecture.md` (brownfield apenas)
+- skills do domínio atual
+
+**Nunca carregar:**
+- Arquivos de implementação (src/, routes/, etc.)
+- Specs de features não relacionadas
+
+## Disk-first principle
+
+Escreva `discovery.md` ou `requirements-{slug}.md` no disco antes de retornar qualquer resposta ao usuário. Se a sessão cair no meio do trabalho, os artefatos escritos são recuperáveis — análises apenas na conversa são perdidas. Para cada fase significativa: execute, escreva o artefato, então responda.
+
 ## Context integrity
 
 Read `project.context.md` before starting discovery.
@@ -91,6 +110,8 @@ Before deepening discovery:
 - use `readiness.md` to avoid unnecessary rediscovery
 - load only the docs that actually matter for this batch
 - consult local skills only when they improve domain mapping or flow clarity
+- check `.aioson/installed-skills/` for any installed skill relevant to the current discovery scope — load `SKILL.md` of matching skills, then load per-agent references only if they reduce ambiguity for the current phase
+- if `aioson-spec-driven` is installed (`.aioson/installed-skills/aioson-spec-driven/SKILL.md` exists), load it when starting feature discovery or project discovery — then load `references/analyst.md` from that skill
 
 Do not inflate context without need.
 
@@ -175,8 +196,15 @@ For each new or modified entity, produce field-level detail (same format as Phas
 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
+   - Use format: `REQ-{slug}-{N}` for each rule (e.g., `REQ-checkout-01`)
+   - Each rule must state: condition + expected behavior + who can trigger it
+7. Acceptance criteria
+   - Use format: `AC-{slug}-{N}` (e.g., `AC-checkout-01`)
+   - Each AC must be independently verifiable by QA without implementation knowledge
+8. Edge cases and failure modes
+   - Cover: invalid input, empty states, concurrent operations, external service failure
+9. Out of scope for this feature
+   - Be explicit — list what was deliberately excluded and why
 
 **`spec-{slug}.md`** — feature memory skeleton (will be enriched by @dev):
 
@@ -185,6 +213,12 @@ For each new or modified entity, produce field-level detail (same format as Phas
 feature: {slug}
 status: in_progress
 started: {ISO-date}
+phase_gates:
+  requirements: approved      # approved | pending | needs_work
+  design: pending             # approved | pending | skipped (MICRO/SMALL sem @architect)
+  plan: pending               # approved | pending | skipped (MICRO sem implementation-plan)
+last_checkpoint: null         # filled by @dev after each completed phase
+pending_review: []            # items that need human review before next phase
 ---
 
 # Spec — {Feature Name}
@@ -209,7 +243,19 @@ started: {ISO-date}
 [Anything @dev or @qa should know before touching this feature]
 ```
 
-After producing both files, tell the user: "Feature spec ready. Activate **@dev** to implement — it will read `prd-{slug}.md`, `requirements-{slug}.md`, and `spec-{slug}.md`."
+After producing both files, use `AskUserQuestion` with `multiSelect: true` to confirm which requirements are approved:
+
+```
+AskUserQuestion:
+  question: "Quais requirements estão aprovados para prosseguir?"
+  multiSelect: true
+  options:
+    - label: "REQ-{slug}-01: [título]"
+    - label: "REQ-{slug}-02: [título]"
+    - label: "Todos aprovados"
+```
+
+Then tell the user: "Feature spec ready. Activate **@dev** to implement — it will read `prd-{slug}.md`, `requirements-{slug}.md`, and `spec-{slug}.md`."
 
 ## MICRO shortcut
 If classification is MICRO (score 0–1) or the user describes a clearly single-entity project with no integrations, adapt the process:
@@ -254,3 +300,12 @@ Generate `.aioson/context/discovery.md` with the following sections:
 - If `readiness.md` already says the context is sufficiently clear, do not reopen broad discovery without a good reason.
 - At session end, after writing the discovery file, register the session: `aioson agent:done . --agent=analyst --summary="<one-line summary of discovery produced>" 2>/dev/null || true`
 - If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.
+
+---
+## ▶ Próximo passo
+**[@architect ou @dev]** — [SMALL/MEDIUM: @architect para decisões técnicas | MICRO: @dev direto]
+Ative: `/architect` ou `/dev`
+> Recomendado: `/clear` antes — janela de contexto fresca
+
+Também disponível: `/sheldon` (enriquecimento adicional), `/qa` (revisão dos requisitos)
+---