@jaimevalasek/aioson 1.9.3 → 1.16.0

package/src/operator-memory/proposal.js

@@ -0,0 +1,179 @@
+'use strict';
+
+/**
+ * operator-memory — proposal CRUD (Phase 2, v1.13.0).
+ *
+ * Proposals are the pending-promotion queue. Each first detection writes a
+ * proposal at proposals/{slug}.md with detected_count=1. Second detection
+ * triggers promotion (see decision.js) — proposal removed, decision created
+ * atomically via SQLite transaction wrapping fs ops.
+ *
+ * Schema (frontmatter-only file, no body):
+ *   ---
+ *   slug: ...
+ *   signal_type: authorization | exclusion | correction | confirmation
+ *   detected_count: 1
+ *   first_detected: <ISO>
+ *   last_detected: <ISO>
+ *   quotes: [verbatim, ...] (capped at 5)
+ *   proposal: <paraphrase>
+ *   source_agent: <agent_name>
+ *   proposal_fingerprint: <sha256[0..12]>
+ *   ---
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { ensureStorageTree, getStorageRoot } = require('./storage');
+const { fingerprintProposal } = require('./slug');
+
+const MAX_QUOTES = 5;
+const VALID_SIGNAL_TYPES = ['authorization', 'exclusion', 'correction', 'confirmation'];
+
+function proposalPath(identity, slug) {
+  return path.join(getStorageRoot(identity), 'proposals', `${slug}.md`);
+}
+
+function escapeYamlString(value) {
+  const s = String(value || '');
+  // Simple: wrap in single quotes; escape embedded single quotes
+  return `'${s.replace(/'/g, "''")}'`;
+}
+
+function quotesToYaml(quotes) {
+  if (!quotes || quotes.length === 0) return '[]';
+  return '\n' + quotes.map((q) => `  - ${escapeYamlString(q)}`).join('\n');
+}
+
+function serializeProposal(data) {
+  return [
+    '---',
+    `slug: ${data.slug}`,
+    `signal_type: ${data.signal_type}`,
+    `detected_count: ${data.detected_count}`,
+    `first_detected: ${data.first_detected}`,
+    `last_detected: ${data.last_detected}`,
+    `quotes:${quotesToYaml(data.quotes)}`,
+    `proposal: ${escapeYamlString(data.proposal)}`,
+    `source_agent: ${data.source_agent}`,
+    `proposal_fingerprint: ${data.proposal_fingerprint}`,
+    '---',
+    ''
+  ].join('\n');
+}
+
+function parseProposalFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const block = match[1];
+  const out = {};
+  let inQuotes = false;
+  let quotes = [];
+  for (const rawLine of block.split('\n')) {
+    if (rawLine.startsWith('quotes:')) {
+      const after = rawLine.slice('quotes:'.length).trim();
+      if (after === '[]' || after === '') {
+        if (after === '[]') { inQuotes = false; out.quotes = []; continue; }
+        inQuotes = true; quotes = []; continue;
+      }
+      inQuotes = true; quotes = []; continue;
+    }
+    if (inQuotes) {
+      const m = rawLine.match(/^\s+-\s+'?([\s\S]*?)'?\s*$/);
+      if (m) {
+        quotes.push(m[1].replace(/''/g, "'"));
+        continue;
+      } else {
+        inQuotes = false;
+        out.quotes = quotes;
+        // fall through to parse this line as a regular field
+      }
+    }
+    const fieldMatch = rawLine.match(/^([a-z_]+):\s*(.*)$/);
+    if (fieldMatch) {
+      const [, key, rawValue] = fieldMatch;
+      let value = rawValue.trim();
+      if (value.startsWith("'") && value.endsWith("'")) {
+        value = value.slice(1, -1).replace(/''/g, "'");
+      }
+      if (/^\d+$/.test(value)) value = Number(value);
+      out[key] = value;
+    }
+  }
+  if (inQuotes) out.quotes = quotes;
+  if (!out.quotes) out.quotes = [];
+  return out;
+}
+
+function readProposal(identity, slug) {
+  const filePath = proposalPath(identity, slug);
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath, 'utf8');
+  return parseProposalFrontmatter(content);
+}
+
+function writeProposal(identity, data) {
+  ensureStorageTree(identity);
+  const filePath = proposalPath(identity, data.slug);
+  const tmpPath = `${filePath}.tmp`;
+  fs.writeFileSync(tmpPath, serializeProposal(data), 'utf8');
+  fs.renameSync(tmpPath, filePath);
+  return filePath;
+}
+
+function deleteProposal(identity, slug) {
+  const filePath = proposalPath(identity, slug);
+  if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+    return true;
+  }
+  return false;
+}
+
+function captureSignal({ identity, slug, signal_type, quote, proposal, source_agent }) {
+  if (!VALID_SIGNAL_TYPES.includes(signal_type)) {
+    throw new Error(`Invalid signal_type '${signal_type}'. Must be one of: ${VALID_SIGNAL_TYPES.join(', ')}`);
+  }
+  const now = new Date().toISOString();
+  const existing = readProposal(identity, slug);
+
+  if (existing) {
+    existing.detected_count = Number(existing.detected_count || 1) + 1;
+    existing.last_detected = now;
+    const trimmedQuote = String(quote || '').trim();
+    if (trimmedQuote && !existing.quotes.includes(trimmedQuote)) {
+      existing.quotes.push(trimmedQuote);
+      if (existing.quotes.length > MAX_QUOTES) {
+        existing.quotes = existing.quotes.slice(-MAX_QUOTES);
+      }
+    }
+    writeProposal(identity, existing);
+    return { proposal: existing, isNew: false };
+  }
+
+  const fresh = {
+    slug,
+    signal_type,
+    detected_count: 1,
+    first_detected: now,
+    last_detected: now,
+    quotes: quote ? [String(quote).trim()].filter(Boolean) : [],
+    proposal,
+    source_agent: source_agent || 'unknown',
+    proposal_fingerprint: fingerprintProposal(proposal)
+  };
+  writeProposal(identity, fresh);
+  return { proposal: fresh, isNew: true };
+}
+
+module.exports = {
+  captureSignal,
+  readProposal,
+  writeProposal,
+  deleteProposal,
+  proposalPath,
+  serializeProposal,
+  parseProposalFrontmatter,
+  MAX_QUOTES,
+  VALID_SIGNAL_TYPES
+};

package/src/operator-memory/prune.js

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * operator-memory — hard cap enforcement (Phase 5, v1.16.0).
+ *
+ * PMD-04: 10k memories per operator identity. When op:promote would push
+ * count > cap, prune oldest non-identity decisions first; identity-category
+ * decisions are NEVER auto-pruned.
+ *
+ * Override cap for tests via AIOSON_OPERATOR_MAX_DECISIONS env var.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { getStorageRoot } = require('./storage');
+const { readDecision, decisionPath, historyPath, forgetEntry } = require('./decision');
+const { listDecisionSlugs } = require('./index-md');
+
+const DEFAULT_MAX_DECISIONS = 10_000;
+
+function getMaxDecisions() {
+  const override = process.env.AIOSON_OPERATOR_MAX_DECISIONS;
+  if (override && !Number.isNaN(Number(override))) {
+    return Number(override);
+  }
+  return DEFAULT_MAX_DECISIONS;
+}
+
+/**
+ * Count active decisions for an identity.
+ */
+function countDecisions(identity) {
+  return listDecisionSlugs(identity).length;
+}
+
+/**
+ * Identify pruning candidates: non-identity-category decisions sorted by
+ * last_reinforced ASC (oldest first).
+ *
+ * @param {number} need — number of pruning slots needed
+ * @returns {Array<{slug, category, last_reinforced}>}
+ */
+function pickPruneCandidates(identity, need) {
+  if (need <= 0) return [];
+  const slugs = listDecisionSlugs(identity);
+  const candidates = [];
+  for (const slug of slugs) {
+    const d = readDecision(identity, slug);
+    if (!d) continue;
+    if (d.category === 'identity') continue; // PMD-04: never auto-prune identity
+    candidates.push({ slug, category: d.category, last_reinforced: d.last_reinforced || d.promoted_at });
+  }
+  candidates.sort((a, b) => String(a.last_reinforced || '').localeCompare(String(b.last_reinforced || '')));
+  return candidates.slice(0, need);
+}
+
+/**
+ * Enforce hard cap before allowing an op:promote to proceed.
+ * Returns array of pruned slug names (empty when under cap).
+ */
+function enforceCap(identity, options = {}) {
+  const cap = options.cap || getMaxDecisions();
+  const current = countDecisions(identity);
+  if (current < cap) return [];
+  const need = current - cap + 1; // +1 to make room for the incoming promote
+  const candidates = pickPruneCandidates(identity, need);
+  const pruned = [];
+  for (const c of candidates) {
+    const result = forgetEntry(identity, c.slug);
+    if (result.mode === 'decision') pruned.push(c.slug);
+  }
+  return pruned;
+}
+
+module.exports = {
+  enforceCap,
+  countDecisions,
+  pickPruneCandidates,
+  getMaxDecisions,
+  DEFAULT_MAX_DECISIONS
+};

package/src/operator-memory/slug.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * operator-memory — deterministic slug derivation (Phase 2, v1.13.0).
+ *
+ * Same proposal text → same slug. Collision suffix appended if slug already
+ * taken by a different proposal text (sha256 fingerprint comparison).
+ *
+ * AC-P2-02: derivation is deterministic + collision-safe.
+ */
+
+const crypto = require('node:crypto');
+
+const MAX_SLUG_LENGTH = 40;
+const STOPWORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'of', 'to', 'for', 'in', 'on', 'with', 'is', 'be',
+  'que', 'de', 'em', 'para', 'sem', 'com', 'um', 'uma', 'os', 'as', 'no', 'na'
+]);
+
+function normalize(text) {
+  return String(text || '')
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')           // strip diacritics
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]+/g, ' ')             // non-alnum -> space
+    .split(/\s+/)
+    .filter((w) => w && !STOPWORDS.has(w))
+    .join('-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function truncateAtBoundary(slug, max) {
+  if (slug.length <= max) return slug;
+  const sliced = slug.slice(0, max);
+  const lastDash = sliced.lastIndexOf('-');
+  if (lastDash > max * 0.6) {
+    return sliced.slice(0, lastDash);
+  }
+  return sliced;
+}
+
+function fingerprintProposal(text) {
+  return crypto.createHash('sha256').update(String(text || '').trim()).digest('hex').slice(0, 12);
+}
+
+/**
+ * Derive a slug from a proposal text.
+ *
+ * @param {string} proposalText — the canonical proposal paraphrase
+ * @param {(slug: string) => string|null} existsCheck — optional callback returning
+ *   the existing proposal's fingerprint for `slug` if taken, or null. Used to
+ *   detect same-slug-different-text collisions.
+ * @returns {string} slug
+ */
+function deriveSlug(proposalText, existsCheck = null) {
+  const normalized = normalize(proposalText);
+  const base = normalized === '' ? 'untitled' : truncateAtBoundary(normalized, MAX_SLUG_LENGTH);
+  const proposalFingerprint = fingerprintProposal(proposalText);
+
+  if (typeof existsCheck !== 'function') {
+    return base;
+  }
+
+  let candidate = base;
+  let counter = 2;
+  while (counter < 100) {
+    const existingFingerprint = existsCheck(candidate);
+    if (existingFingerprint === null || existingFingerprint === undefined) {
+      // slug available
+      return candidate;
+    }
+    if (existingFingerprint === proposalFingerprint) {
+      // same proposal text — reuse slug (idempotent capture)
+      return candidate;
+    }
+    // collision: different proposal at same slug — append counter
+    candidate = `${base}-${counter}`;
+    counter += 1;
+  }
+  // extreme collision fallback (should never hit in practice)
+  return `${base}-${proposalFingerprint.slice(0, 8)}`;
+}
+
+module.exports = {
+  deriveSlug,
+  normalize,
+  fingerprintProposal,
+  MAX_SLUG_LENGTH
+};

package/src/operator-memory/storage.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * operator-memory — storage tree + _index.sqlite (Phase 1, v1.12.0).
+ *
+ * Markdown is source-of-truth (PMD-AN-06); SQLite is regenerable index (FTS5).
+ * Phase 1 creates the schema (operators + decisions_fts virtual table). Phase 2
+ * activates FTS5 mirroring from op:capture/op:promote.
+ *
+ * Storage tree (architecture-operator-memory.md § Storage architecture):
+ *   ~/.aioson/operators/
+ *   ├── _index.sqlite          shared across identities (PMD-01 hybrid)
+ *   └── {identity}/
+ *       ├── decisions/         Phase 2 populates
+ *       ├── proposals/         Phase 2 populates
+ *       └── history/           Phase 2+5 populates
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const Database = require('better-sqlite3');
+
+const ROOT_DIR_NAME = '.aioson';
+const OPERATORS_SUBDIR = 'operators';
+const INDEX_DB_FILE = '_index.sqlite';
+const SCHEMA_VERSION = 1;
+
+function getRootDir() {
+  return path.join(os.homedir(), ROOT_DIR_NAME, OPERATORS_SUBDIR);
+}
+
+function getStorageRoot(identity) {
+  if (typeof identity !== 'string' || identity === '') {
+    throw new Error('getStorageRoot: identity must be a non-empty string');
+  }
+  return path.join(getRootDir(), identity);
+}
+
+function getIndexDbPath() {
+  return path.join(getRootDir(), INDEX_DB_FILE);
+}
+
+function ensureStorageTree(identity) {
+  const root = getStorageRoot(identity);
+  fs.mkdirSync(path.join(root, 'decisions'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'proposals'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'history'), { recursive: true });
+  return root;
+}
+
+function migrateIndexSchema(db) {
+  db.pragma('journal_mode = WAL');
+  db.pragma('synchronous = NORMAL');
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_version (
+      version INTEGER PRIMARY KEY
+    );
+
+    CREATE TABLE IF NOT EXISTS operators (
+      identity       TEXT PRIMARY KEY,
+      created_at     TEXT NOT NULL,
+      source         TEXT NOT NULL,
+      last_active_at TEXT NOT NULL
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS decisions_fts USING fts5(
+      identity        UNINDEXED,
+      slug            UNINDEXED,
+      signal_type,
+      category,
+      body,
+      last_reinforced UNINDEXED,
+      tokenize = 'porter'
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_operators_last_active
+      ON operators(last_active_at);
+  `);
+
+  const existing = db.prepare('SELECT version FROM schema_version LIMIT 1').get();
+  if (!existing) {
+    db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(SCHEMA_VERSION);
+  }
+}
+
+function openIndexDb() {
+  const rootDir = getRootDir();
+  fs.mkdirSync(rootDir, { recursive: true });
+  const dbPath = getIndexDbPath();
+  const db = new Database(dbPath);
+  migrateIndexSchema(db);
+  return db;
+}
+
+function recordIdentityActivity(db, { identity, source }) {
+  const now = new Date().toISOString();
+  const existing = db.prepare('SELECT identity FROM operators WHERE identity = ?').get(identity);
+  if (existing) {
+    db.prepare('UPDATE operators SET last_active_at = ? WHERE identity = ?').run(now, identity);
+  } else {
+    db.prepare(
+      'INSERT INTO operators (identity, created_at, source, last_active_at) VALUES (?, ?, ?, ?)'
+    ).run(identity, now, source, now);
+  }
+}
+
+module.exports = {
+  getRootDir,
+  getStorageRoot,
+  getIndexDbPath,
+  ensureStorageTree,
+  openIndexDb,
+  migrateIndexSchema,
+  recordIdentityActivity,
+  SCHEMA_VERSION,
+  INDEX_DB_FILE,
+  ROOT_DIR_NAME,
+  OPERATORS_SUBDIR
+};

package/src/preflight-engine.js

@@ -322,8 +322,14 @@ async function readDevState(targetDir) {
   const filePath = path.join(contextDir(targetDir), 'dev-state.md');
   const content = await readFileSafe(filePath);
   if (!content) return { exists: false };
+  // F1 (workflow-handoff-integrity v1.9.7) — corrupt detection (AC-F1-08).
+  // dev-state.md by convention ALWAYS has frontmatter; missing markers OR
+  // unparseable frontmatter both indicate corruption.
+  const hasFrontmatterMarkers = /^---\r?\n[\s\S]*?\r?\n---/.test(content);
   const fm = parseFrontmatter(content);
-  return { exists: true, ...fm, content };
+  const fmIsEmpty = Object.keys(fm).length === 0;
+  const parseError = content.trim().length > 0 && (!hasFrontmatterMarkers || fmIsEmpty);
+  return { exists: true, parseError, ...fm, content };
 }
 
 // ─── Project pulse reader ────────────────────────────────────────────────────
@@ -486,8 +492,18 @@ function buildContextPackage(agent, slug, classification, artifacts, devState, m
 
 // ─── Stale dev-state detection ───────────────────────────────────────────────
 
+/**
+ * Stale dev-state detection — synchronous baseline.
+ *
+ * F1 (workflow-handoff-integrity v1.9.7) extends the previous 2-condition logic
+ * with parseError detection (AC-F1-08). For richer detection (orphan in
+ * features.md, TTL > 30d), use the async `detectStaleDevStateRich` instead.
+ */
 function detectStaleDevState(devState, slug) {
   if (!devState.exists) return null;
+  if (devState.parseError) {
+    return `dev-state.md is corrupt (missing or unparseable frontmatter) — cannot trust as active context. Run \`aioson state:reset\` to clear, then \`aioson state:save --feature=<slug>\` for the current feature`;
+  }
   if (devState.status === 'done') {
     return `dev-state.md is marked done (feature: ${devState.active_feature || 'unknown'}) — it belongs to a completed session and should not be used as active context`;
   }
@@ -497,6 +513,78 @@ function detectStaleDevState(devState, slug) {
   return null;
 }
 
+/**
+ * Stale dev-state detection — async + features-aware.
+ *
+ * F1 (workflow-handoff-integrity v1.9.7) — extends `detectStaleDevState` with:
+ *   - (a) feature marked `done` or `abandoned` in features.md
+ *   - (b) feature absent from features.md (orphan / cross-project leak)
+ *   - (c) `last_updated` > 30 days vs now
+ *
+ * All warnings embed an actionable command suggestion (state:reset or state:save)
+ * per AC-F1-01.
+ *
+ * @param {object} devState   Result of `readDevState`.
+ * @param {string|null} slug  Active feature slug (for mismatch check).
+ * @param {string} targetDir  Project root (used to read features.md).
+ * @param {number} [now]      Override Date.now() for testing.
+ * @returns {Promise<string|null>}  Warning string or null when not stale.
+ */
+async function detectStaleDevStateRich(devState, slug, targetDir, now = Date.now()) {
+  // Sync baseline first — corrupt / done / mismatch.
+  const baseline = detectStaleDevState(devState, slug);
+  if (baseline) return baseline;
+  if (!devState.exists || !devState.active_feature) return null;
+
+  // (a)+(b) — cross-reference features.md.
+  const featuresPath = path.join(contextDir(targetDir), 'features.md');
+  const featuresContent = await readFileSafe(featuresPath);
+  if (featuresContent) {
+    const featuresMap = parseFeaturesMap(featuresContent);
+    const featureStatus = featuresMap.get(devState.active_feature);
+    if (featureStatus === 'done' || featureStatus === 'abandoned') {
+      return `dev-state.md points to feature "${devState.active_feature}" already marked \`${featureStatus}\` in features.md — run \`aioson state:reset\` to clear, then \`aioson state:save --feature=<new>\` for the next feature`;
+    }
+    if (featureStatus === undefined && featuresMap.size > 0) {
+      return `dev-state.md points to feature "${devState.active_feature}" not present in features.md (orphan or cross-project leak) — run \`aioson state:reset\` to clear`;
+    }
+  }
+
+  // (c) — TTL check.
+  if (devState.last_updated) {
+    const lastUpdatedTs = Date.parse(devState.last_updated);
+    if (!Number.isNaN(lastUpdatedTs)) {
+      const ageMs = now - lastUpdatedTs;
+      const THIRTY_DAYS = 30 * 24 * 60 * 60 * 1000;
+      if (ageMs > THIRTY_DAYS) {
+        const days = Math.round(ageMs / (24 * 60 * 60 * 1000));
+        return `dev-state.md is ${days} days old (last_updated: ${devState.last_updated}) — likely stale. Run \`aioson state:reset\` or \`aioson state:save --feature=<current>\` to refresh`;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse features.md table into Map<slug, status>.
+ * Tolerant of malformed rows and trailing whitespace.
+ */
+function parseFeaturesMap(content) {
+  const map = new Map();
+  for (const line of String(content || '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    const parts = trimmed.split('|').map((p) => p.trim());
+    if (parts.length < 5) continue;
+    const slug = parts[1];
+    const status = parts[2];
+    if (!slug || slug === 'slug' || /^-+$/.test(slug)) continue;
+    map.set(slug, status);
+  }
+  return map;
+}
+
 // ─── Readiness evaluator ─────────────────────────────────────────────────────
 
 function evaluateReadiness(artifacts, phaseGates, classification, agent, devState, slug) {
@@ -638,6 +726,8 @@ module.exports = {
   parseGatesFromSpec,
   readPhaseGates,
   readDevState,
+  detectStaleDevStateRich,
+  parseFeaturesMap,
   readProjectPulse,
   detectClassification,
   parseAgentList,

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

@@ -284,7 +284,7 @@ Interface copy, onboarding text, email content, and marketing text are not withi
 
 ## Hard constraints
 - Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction/output.
-- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). Always use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option.
+- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
 - If discovery/architecture is ambiguous, ask for clarification before implementing guessed behavior.
 - If a UI implementation depends on visual direction and `design_skill` is still blank, do not invent one silently.
 - No unnecessary rewrites outside current responsibility.

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

@@ -96,8 +96,8 @@ Run this after the immediate scope gate and before touching code:
 Behave like a senior engineer sitting next to the user:
 - start by summarizing the latest confirmed context
 - say what is confirmed vs inferred when memory is incomplete
-- ask what the user wants to do now when the immediate next slice is unclear
-- propose the smallest sensible next step
+- if no specific task is provided and no active feature requires continuation, stop after the context summary and wait for the user to direct — do NOT emit `AskUserQuestion` with fabricated options or invent next steps (see decision-presentation Rule 7)
+- when the user has stated a task, propose the smallest sensible next step
 - implement, inspect, or fix one small validated batch at a time
 - stop and hand off when the task broadens beyond pair-session boundaries
 
@@ -185,7 +185,7 @@ Dispatch via harness sub-agent with the tool whitelist `[Read, Grep]`. Read the
 ## Hard constraints
 
 - Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction and output.
-- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). Always use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option.
+- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
 - Always check `.aioson/rules/` and relevant `.aioson/docs/` when they exist.
 - Always apply relevant `.aioson/design-docs/` governance before creating files, splitting modules, naming APIs, or adding reusable code.
 - Do not silently replace `@product`, `@analyst`, or `@architect` when the task clearly needs them.

package/template/.aioson/agents/neo.md

@@ -335,7 +335,7 @@ clarification: none | [specific question if confidence is low]
 - Do not write to any file or directory
 - Do not activate another agent — only tell the user which to activate
 - Do not continue into another agent's work after routing
-- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). Always use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option.
+- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
 - Use `interaction_language` from context for all interaction. If it is absent, fall back to `conversation_language`.
 - If `aioson` CLI is available, suggest `aioson workflow:next .` as an alternative tracked path
 

package/template/.aioson/agents/product.md

@@ -341,7 +341,7 @@ If a question is outside product scope, acknowledge it briefly and redirect: "Th
 
 ## Hard constraints
 - Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction and output.
-- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). Always use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option.
+- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
 - Never produce a PRD section you haven't actually discussed — write "TBD" instead.
 - Keep PRD files focused: if a section is growing beyond 5 bullet points, summarize.
 - Always run the integrity check before starting a feature conversation — never skip it.

package/template/.aioson/agents/setup.md

@@ -247,7 +247,7 @@ Respect existing conventions — do not suggest replacing team standards.
 
 ## Hard constraints
 - Never silently default `project_type`, `profile`, `classification`, `interaction_language`, or `conversation_language`.
-- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). Always use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option.
+- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
 - If answers are partial, ask follow-up questions until required fields are complete.
 - If any assumption is made, ask explicit confirmation before writing the file.
 

package/template/.aioson/docs/deyvin/pair-execution.md

@@ -9,7 +9,7 @@ Load this module when `@deyvin` is about to inspect, explain, fix, or implement
 ## Pair working style
 
 - summarize the latest confirmed context first
-- ask what the user wants to do now if the next step is unclear
+- if the user has not stated a task, summarize the context and wait — never fabricate `AskUserQuestion` options just because the agent loaded (see decision-presentation Rule 7)
 - propose the smallest sensible next step
 - implement, inspect, or fix one small batch at a time
 - validate before moving on