@jaimevalasek/aioson 1.9.0 → 1.9.2

package/src/installer.js

@@ -9,6 +9,7 @@ const { ensureProjectRuntime } = require('./execution-gateway');
 const { shouldIncludeForProfile } = require('./install-profile');
 const { generatePermissions } = require('./permissions-generator');
 const { isConfigMergePath, mergeConfigFile } = require('./installer-config-merge');
+const { isGatewayPointerPath, mergeGatewayPointer } = require('./gateway-pointer-merge');
 
 const ROOT_DIR = path.join(__dirname, '..');
 const TEMPLATE_DIR = path.join(ROOT_DIR, 'template');
@@ -67,7 +68,10 @@ const GITIGNORE_POLICY_LINES = [
   '.aioson/profiler-reports/*',
   '!.aioson/profiler-reports/.gitkeep',
   '.claude/settings.local.json',
-  '*:Zone.Identifier'
+  '*:Zone.Identifier',
+  '# AIOSON — shared agent scratch caches (local-only)',
+  'researchs/',
+  'squad-searches/'
 ];
 
 async function detectExistingInstall(targetDir) {
@@ -341,6 +345,40 @@ async function installTemplate(targetDir, options = {}) {
     const dest = path.join(targetDir, rel);
     const destExists = await exists(dest);
 
+    // Gateway pointer files (CLAUDE.md, AGENTS.md, OPENCODE.md, .gemini/GEMINI.md)
+    // get block-merged so that an existing project-authored file keeps its content
+    // and only the AIOSON-managed block is created or refreshed in place.
+    if (isGatewayPointerPath(rel)) {
+      if (!destExists && selectiveUpdate) {
+        skipped.push({ path: rel, reason: 'not-installed' });
+        continue;
+      }
+      const mergeResult = await mergeGatewayPointer({
+        templatePath: absPath,
+        targetPath: dest,
+        backupRoot: backupOnOverwrite ? backupRoot : null,
+        targetDir,
+        dryRun
+      });
+      if (mergeResult.action === 'unchanged') {
+        skipped.push({ path: rel, reason: 'unchanged' });
+      } else {
+        copied.push(rel);
+        mergedConfigs.push({ path: rel, action: mergeResult.action });
+        if (mergeResult.backupPath) {
+          backedUp.push(toRelativeSafe(targetDir, mergeResult.backupPath));
+        }
+        if (mergeResult.backupError) {
+          failedBackups.push({ path: rel, error: mergeResult.backupError });
+          console.warn(`[aioson update] backup of ${rel} failed; update proceeding without rollback for this file: ${mergeResult.backupError}`);
+        }
+      }
+      if (onProgress) {
+        onProgress({ copied: copied.length, total: templateFiles.length, file: rel });
+      }
+      continue;
+    }
+
     // Project-local files are never overwritten from template.
     // On fresh install they are created once; on any subsequent operation they are preserved
     // even if the file was manually deleted.

package/src/jargon-leak-doctor.js

@@ -0,0 +1,257 @@
+'use strict';
+
+/**
+ * lay-user-agent-mode — Phase 3 doctor check `jargon_leak_detection`.
+ *
+ * Pure-where-possible helpers consumed by `src/doctor.js#runDoctor`. The check
+ * scans `agent_events` rows from the 5 MVP agents (neo, setup, product, dev,
+ * deyvin) and flags occurrences of framework jargon (MICRO/SMALL/MEDIUM, Gate
+ * A-D, tier1/2/3, etc.) emitted while the project's profile is `creator`.
+ *
+ * Profile semantics (lay-user-agent-mode E4):
+ *   - profile=creator (or absent/auto/empty) → run the check
+ *   - profile=developer → skip (jargon permitted; ok=true with skipped marker)
+ *   - profile=team     → skip (jargon permitted in operator-facing flow)
+ *
+ * Word-boundary matching: case-sensitive `\b{term}\b` semantics implemented
+ * via non-word lookarounds so multi-word keys ("Gate D") match correctly and
+ * substring hits ("MICRO" inside "MICROserviços") DO NOT trigger.
+ *
+ * EC-LUM-05: missing/empty runtime DB → ok=true count=0 (greenfield).
+ * EC-LUM-08: missing/deleted jargon-map → ok=true count=0 with marker.
+ * EC-LUM-10: 50+ leaks → samples truncated to MAX_SAMPLES.
+ * EC-LUM-11: future enhancement — `payload_json.jargon_intentional=true` opt-out.
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const MVP_AGENTS = ['neo', 'setup', 'product', 'dev', 'deyvin'];
+const MAX_SAMPLES = 10;
+const MAX_EVENTS_SCANNED = 500;
+const JARGON_MAP_REL = '.aioson/skills/process/decision-presentation/references/jargon-map.en.yaml';
+
+// Extract canonical term keys from the YAML's `terms:` block without pulling
+// in a YAML parser. Schema is fixed by E2 (version: 1, terms: { KEY: {...} }).
+// Keys are either bare identifiers (MICRO) or quoted ("Gate D").
+function extractTermKeys(yamlContent) {
+  if (typeof yamlContent !== 'string') return [];
+  const inTermsMatch = yamlContent.match(/^terms:\s*\n([\s\S]*)$/m);
+  if (!inTermsMatch) return [];
+  const keys = [];
+  const lines = inTermsMatch[1].split('\n');
+  for (const line of lines) {
+    // 2-space indent, then key (bare or quoted), then trailing colon.
+    const m = line.match(/^  (?:"([^"]+)"|'([^']+)'|([A-Za-z_][^:\s]*)):\s*$/);
+    if (m) keys.push(m[1] || m[2] || m[3]);
+  }
+  return keys;
+}
+
+async function loadJargonTerms(targetDir) {
+  try {
+    const raw = await fs.readFile(path.join(targetDir, JARGON_MAP_REL), 'utf8');
+    return extractTermKeys(raw);
+  } catch {
+    return [];
+  }
+}
+
+async function readProjectProfile(targetDir) {
+  try {
+    const raw = await fs.readFile(
+      path.join(targetDir, '.aioson/context/project.context.md'),
+      'utf8'
+    );
+    const m = raw.match(/^profile\s*:\s*["']?([\w-]+)["']?/m);
+    return m ? m[1].toLowerCase() : null;
+  } catch {
+    return null;
+  }
+}
+
+// Default-profile rule from the skill: absent/empty/auto → creator (safer).
+// Legacy `beginner` already migrated by src/migrations/profile-rename, but
+// accept it defensively in case migration didn't run.
+function normalizeEffectiveProfile(raw) {
+  if (!raw) return 'creator';
+  const v = String(raw).toLowerCase();
+  if (v === 'auto' || v === '') return 'creator';
+  if (v === 'beginner') return 'creator';
+  return v;
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Build one alternation regex with all terms. Non-word lookarounds enforce
+// word-boundary semantics WITHOUT \b (which fails for terms containing
+// spaces, like "Gate D"). Treat hyphen as a word char so terms like
+// "harness-contract" do not split on the dash.
+function buildJargonRegex(terms) {
+  if (!terms || terms.length === 0) return null;
+  // Sort longest-first so "Gate D" wins over a hypothetical "Gate" key.
+  const sorted = [...terms].sort((a, b) => b.length - a.length);
+  const alt = sorted.map(escapeRegex).join('|');
+  return new RegExp(`(?<![\\w-])(${alt})(?![\\w-])`, 'g');
+}
+
+// Find all term occurrences in a string. Returns the matched substrings.
+function findLeaks(text, regex) {
+  if (!text || !regex) return [];
+  const out = [];
+  regex.lastIndex = 0;
+  let m;
+  while ((m = regex.exec(text)) !== null) {
+    out.push(m[1]);
+  }
+  return out;
+}
+
+// Pure: detect leaks across a list of event records. Truncates samples to
+// MAX_SAMPLES; `count` reflects the total occurrence count across all events.
+function detectJargonInEvents(events, terms) {
+  const regex = buildJargonRegex(terms);
+  const samples = [];
+  let count = 0;
+  if (!regex || !Array.isArray(events)) return { count, samples };
+
+  for (const ev of events) {
+    if (!ev) continue;
+    const message = typeof ev.message === 'string' ? ev.message : '';
+    const payload = typeof ev.payload_json === 'string' ? ev.payload_json : '';
+
+    // EC-LUM-11 opt-out: explicit `jargon_intentional: true` skips this event.
+    if (payload) {
+      try {
+        const parsed = JSON.parse(payload);
+        if (parsed && parsed.jargon_intentional === true) continue;
+      } catch {
+        // not JSON — ignore opt-out, treat payload as opaque text below
+      }
+    }
+
+    const hits = [...findLeaks(message, regex), ...findLeaks(payload, regex)];
+    if (hits.length === 0) continue;
+
+    count += hits.length;
+    if (samples.length < MAX_SAMPLES) {
+      samples.push({
+        agent: ev.agent_name || null,
+        created_at: ev.created_at || null,
+        terms: Array.from(new Set(hits)).slice(0, 3),
+        excerpt: message.slice(0, 120)
+      });
+    }
+  }
+  return { count, samples };
+}
+
+/**
+ * Top-level assessment consumed by doctor.js.
+ *
+ * @param {object} opts
+ * @param {object|null} opts.db                better-sqlite3 handle (or null)
+ * @param {string}      opts.targetDir         project root
+ * @param {string[]}    [opts.scope]           agent_name whitelist (defaults to MVP_AGENTS)
+ * @param {number}      [opts.eventLimit]      cap on agent_events scanned
+ *
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   count: number,
+ *   samples: Array<{agent,created_at,terms,excerpt}>,
+ *   profile: string,
+ *   skipped?: boolean,
+ *   reason?: string,
+ *   eventsScanned?: number,
+ *   jargonMapMissing?: boolean
+ * }>}
+ */
+async function assessJargonLeak(opts) {
+  const {
+    db,
+    targetDir,
+    scope = MVP_AGENTS,
+    eventLimit = MAX_EVENTS_SCANNED
+  } = opts || {};
+
+  const rawProfile = await readProjectProfile(targetDir);
+  const profile = normalizeEffectiveProfile(rawProfile);
+
+  // AC-LUM-08: developer/team skip — jargon permitted in those modes.
+  if (profile === 'developer' || profile === 'team') {
+    return {
+      ok: true,
+      skipped: true,
+      reason: 'profile-permits-jargon',
+      profile,
+      count: 0,
+      samples: []
+    };
+  }
+
+  // EC-LUM-05: no runtime DB → fresh project, nothing to scan.
+  if (!db) {
+    return { ok: true, count: 0, samples: [], profile, eventsScanned: 0 };
+  }
+
+  const terms = await loadJargonTerms(targetDir);
+  if (terms.length === 0) {
+    // EC-LUM-08: jargon-map missing — fail open (cannot detect without dict).
+    return {
+      ok: true,
+      count: 0,
+      samples: [],
+      profile,
+      jargonMapMissing: true,
+      eventsScanned: 0
+    };
+  }
+
+  let events;
+  try {
+    const placeholders = scope.map(() => '?').join(',');
+    events = db
+      .prepare(
+        `SELECT ae.message AS message,
+                ae.payload_json AS payload_json,
+                ar.agent_name AS agent_name,
+                ae.created_at AS created_at
+         FROM agent_events ae
+         JOIN agent_runs ar ON ae.run_key = ar.run_key
+         WHERE ar.agent_name IN (${placeholders})
+         ORDER BY ae.created_at DESC
+         LIMIT ?`
+      )
+      .all(...scope, eventLimit);
+  } catch {
+    // Schema drift / missing tables on a stale runtime DB. Treat as greenfield.
+    return { ok: true, count: 0, samples: [], profile, eventsScanned: 0 };
+  }
+
+  const { count, samples } = detectJargonInEvents(events, terms);
+  return {
+    ok: count === 0,
+    count,
+    samples,
+    profile,
+    eventsScanned: events.length
+  };
+}
+
+module.exports = {
+  MVP_AGENTS,
+  MAX_SAMPLES,
+  MAX_EVENTS_SCANNED,
+  JARGON_MAP_REL,
+  extractTermKeys,
+  loadJargonTerms,
+  readProjectProfile,
+  normalizeEffectiveProfile,
+  escapeRegex,
+  buildJargonRegex,
+  findLeaks,
+  detectJargonInEvents,
+  assessJargonLeak
+};

package/src/migrations/profile-rename.js

@@ -0,0 +1,66 @@
+'use strict';
+
+// Migration: project.context.md `profile: beginner` -> `profile: creator`.
+//
+// Why: lay-user-agent-mode renames the persona value from `beginner` (which
+// reads as "tutorial mode" / patronizing) to `creator` (neutral, aligns with
+// vibe-coding market vocabulary). Existing projects on v1.9.0 or earlier may
+// have `profile: beginner` in their project.context.md frontmatter. On the
+// next `aioson update`, this migration rewrites that one line and emits a
+// notify so the user understands the rename.
+//
+// Idempotent: re-running on a project already migrated does nothing.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const PROJECT_CONTEXT_REL = '.aioson/context/project.context.md';
+
+// Match `profile: beginner` with optional surrounding quotes in YAML frontmatter.
+// Anchored to start-of-line to avoid matching prose mentions inside the body.
+const FRONTMATTER_PROFILE_RE = /^profile:\s*["']?beginner["']?\s*$/m;
+
+async function readFileOrNull(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+function rewriteProfileLine(content) {
+  return content.replace(FRONTMATTER_PROFILE_RE, 'profile: creator');
+}
+
+// Returns { changed: boolean, file: string | null }.
+// changed=true means the file was rewritten this run.
+// changed=false means either the file is missing, has no frontmatter,
+// or already says `creator` (or any non-`beginner` value).
+async function migrateProfileRename(targetDir) {
+  const file = path.join(targetDir, PROJECT_CONTEXT_REL);
+  const content = await readFileOrNull(file);
+  if (!content) return { changed: false, file: null };
+
+  // Only touch frontmatter — first --- block at top of file.
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return { changed: false, file };
+
+  if (!FRONTMATTER_PROFILE_RE.test(fmMatch[1])) {
+    return { changed: false, file };
+  }
+
+  const newFrontmatter = rewriteProfileLine(fmMatch[1]);
+  const newContent = content.replace(fmMatch[0], `---\n${newFrontmatter}\n---`);
+  await fs.writeFile(file, newContent, 'utf8');
+
+  return { changed: true, file };
+}
+
+module.exports = {
+  migrateProfileRename,
+  // Exported for tests:
+  rewriteProfileLine,
+  FRONTMATTER_PROFILE_RE,
+  PROJECT_CONTEXT_REL
+};

package/src/onboarding.js

@@ -72,7 +72,7 @@ const SERVICE_ALIASES = {
 
 const PROFILE_CHOICES = {
   '1': 'developer',
-  '2': 'beginner',
+  '2': 'creator',
   '3': 'team'
 };
 
@@ -101,7 +101,9 @@ function normalizeProfile(value, fallback = 'developer') {
     return PROFILE_CHOICES[input];
   }
   const lower = input.toLowerCase();
-  if (['developer', 'beginner', 'team'].includes(lower)) return lower;
+  // Accept legacy 'beginner' as input but normalize to 'creator' (E4 migration shim).
+  if (lower === 'beginner') return 'creator';
+  if (['developer', 'creator', 'team'].includes(lower)) return lower;
   return fallback;
 }
 
@@ -191,14 +193,14 @@ function buildDeveloperProfile(input) {
   };
 }
 
-function recommendBeginnerProfile(input = {}) {
+function recommendCreatorProfile(input = {}) {
   const expectedUsers = normalizeText(input.expectedUsers).toLowerCase();
   const mobileNeed = normalizeText(input.mobileRequirement).toLowerCase();
   const hosting = normalizeText(input.hostingPreference).toLowerCase();
   const summary = normalizeText(input.projectSummary);
 
   const recommendation = {
-    profile: 'beginner',
+    profile: 'creator',
     projectType: 'web_app',
     framework: 'Laravel',
     backend: 'Laravel',
@@ -300,6 +302,6 @@ module.exports = {
   inferProjectTypeFromFramework,
   inferWeb3NetworkFromFramework,
   buildDeveloperProfile,
-  recommendBeginnerProfile,
+  recommendCreatorProfile,
   buildTeamProfile
 };

package/src/parser.js

@@ -10,11 +10,19 @@ function parseArgv(argv) {
     const token = tokens[i];
 
     if (token.startsWith('--')) {
-      const [k, v] = token.replace(/^--/, '').split('=');
-      if (v !== undefined) {
+      // Split on the FIRST `=` only — values may contain `=` (e.g. URLs,
+      // SQL, or natural-language sentences like "profile=creator").
+      // Using `.split('=')` without a limit + array destructuring discards
+      // anything after the second `=`, truncating flag values silently.
+      const stripped = token.slice(2);
+      const eqIdx = stripped.indexOf('=');
+      if (eqIdx !== -1) {
+        const k = stripped.slice(0, eqIdx);
+        const v = stripped.slice(eqIdx + 1);
         options[k] = v;
         continue;
       }
+      const k = stripped;
 
       // Boolean-only flags that never consume the next token
       const boolOnly = new Set([
@@ -22,6 +30,7 @@ function parseArgv(argv) {
         'help', 'version', 'no-launch', 'attach', 'tmux',
         'allow-warnings', 'install-hook', 'uninstall-hook', 'remove-hook',
         'agent-safe',
+        'selective',
         'status', 'suggest', 'apply',
         // `--resume` alone means "resume last"; `--resume=<id>` carries a value
         // and is handled by the `=` branch above. Without this entry, `--resume`

package/src/updater.js

@@ -2,6 +2,7 @@
 
 const path = require('node:path');
 const { detectExistingInstall, installTemplate, readInstallProfile } = require('./installer');
+const { migrateProfileRename } = require('./migrations/profile-rename');
 
 async function updateInstallation(targetDir, options = {}) {
   const installed = await detectExistingInstall(targetDir);
@@ -15,8 +16,12 @@ async function updateInstallation(targetDir, options = {}) {
 
   const savedProfile = await readInstallProfile(targetDir);
 
-  // Default: only update files already present in the target (selective update).
-  // With --all: install every file from the template, including new ones not yet installed.
+  // Default: sync everything from the template, including files added by the
+  // release that aren't yet in the target. Pre-1.9.2 this defaulted to
+  // selective and silently dropped new agents/slash commands between versions.
+  // `--selective` restores the legacy conservative mode; `--all` is accepted
+  // as a backwards-compat no-op since "all" is now the default.
+  const selective = Boolean(options.selective) && !options.all;
   const result = await installTemplate(targetDir, {
     overwrite: true,
     dryRun: Boolean(options.dryRun),
@@ -24,13 +29,25 @@ async function updateInstallation(targetDir, options = {}) {
     backupOnOverwrite: true,
     frameworkDetection: options.frameworkDetection || null,
     installProfile: savedProfile,
-    selectiveUpdate: !options.all
+    selectiveUpdate: selective
   });
 
+  // Post-install migrations. Best-effort: a migration failure must not break
+  // the update flow. Skip migrations in dry-run mode.
+  let profileMigration = { changed: false, file: null };
+  if (!options.dryRun) {
+    try {
+      profileMigration = await migrateProfileRename(targetDir);
+    } catch {
+      // swallow — migrations are advisory
+    }
+  }
+
   return {
     ok: true,
     ...result,
-    savedProfile
+    savedProfile,
+    migrations: { profileRename: profileMigration }
   };
 }
 

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

@@ -329,5 +329,17 @@ Generate `.aioson/context/discovery.md` with the following sections:
 - In feature mode: never duplicate content already in `discovery.md` — only document what is new or changed.
 - If `readiness.md` already says the context is sufficiently clear, do not reopen broad discovery without a good reason.
 
+## 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:
+
+```bash
+aioson dev:state:write . --feature={slug} --phase=1 \
+  --next="<concrete first slice description for @dev>" \
+  --context=spec,requirements
+```
+
+`--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.
+
 ## Observability
 At session end, register: `aioson agent:done . --agent=analyst --summary="Discovery <slug>: <N> entities, <N> rules" 2>/dev/null || true`

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

@@ -215,6 +215,8 @@ If `.aioson/skills/process/secure-tdd/SKILL.md` exists and the active feature is
 
 ## Deterministic preflight
 
+Always load `.aioson/skills/process/decision-presentation/SKILL.md` before the first user-facing question. Mandatory regardless of profile.
+
 Before the first code change, decide which dev docs must be loaded:
 
 | Condition | Required module |
@@ -282,6 +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.
 - 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

@@ -82,13 +82,14 @@ The detailed pair-programming protocol is split into on-demand framework docs:
 
 Run this after the immediate scope gate and before touching code:
 
-1. Always load `.aioson/docs/deyvin/continuity-recovery.md`
-2. If `aioson` is available, run `aioson preflight . --agent=deyvin --feature={slug}` when a feature slug is known; load any listed `rules` and `design_governance` files before touching code
-3. If continuation depends on `spec*.md`, `dev-state.md`, or a feature already in progress, load `.aioson/skills/process/aioson-spec-driven/SKILL.md` and then only `references/deyvin.md`
-4. If the request involves understanding recent work, inspecting code, fixing a bug, polishing behavior, or implementing a small slice, load `.aioson/docs/deyvin/pair-execution.md`
-5. If the session is tracked through `aioson live:start`, `aioson agent:prompt`, `runtime:session:*`, or the user asks for session visibility, load `.aioson/docs/deyvin/runtime-handoffs.md`
-6. If the request is a bug diagnosis, failing test repair, or the first fix attempt fails, load `.aioson/docs/deyvin/debugging-escalation.md`
-7. Do not touch code until all required modules have been loaded
+1. Always load `.aioson/skills/process/decision-presentation/SKILL.md` before the first user-facing question. Mandatory regardless of profile.
+2. Always load `.aioson/docs/deyvin/continuity-recovery.md`
+3. If `aioson` is available, run `aioson preflight . --agent=deyvin --feature={slug}` when a feature slug is known; load any listed `rules` and `design_governance` files before touching code
+4. If continuation depends on `spec*.md`, `dev-state.md`, or a feature already in progress, load `.aioson/skills/process/aioson-spec-driven/SKILL.md` and then only `references/deyvin.md`
+5. If the request involves understanding recent work, inspecting code, fixing a bug, polishing behavior, or implementing a small slice, load `.aioson/docs/deyvin/pair-execution.md`
+6. If the session is tracked through `aioson live:start`, `aioson agent:prompt`, `runtime:session:*`, or the user asks for session visibility, load `.aioson/docs/deyvin/runtime-handoffs.md`
+7. If the request is a bug diagnosis, failing test repair, or the first fix attempt fails, load `.aioson/docs/deyvin/debugging-escalation.md`
+8. Do not touch code until all required modules have been loaded
 
 ## Working kernel
 
@@ -184,6 +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.
 - 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

@@ -17,7 +17,13 @@ Tone: calm, direct, confident. No filler. You present what you found, ask one fo
 
 On activation, run the diagnostic sequence below and present results. Do not wait for user input before running diagnostics.
 
-If `aioson` is available, run `aioson memory:summary . --last=5` before the table scan. Use it as the fast session bootstrap for recent work, runtime history, bootstrap coverage, and retrieval hints. Do not require the user to know or run this command.
+Always load `.aioson/skills/process/decision-presentation/SKILL.md` before the first user-facing question. Mandatory regardless of profile.
+
+If `aioson` is available, run these in parallel before the table scan (Living Memory + harness snapshot — do not require the user to know these commands):
+
+- `aioson memory:status .` — bootstrap coverage (N/4), brains, runtime sessions
+- `aioson memory:summary . --last=5` — recent activity + retrieval hints
+- `aioson workflow:next . --status` — active stage, pending gate, handoff contract
 
 ## Project pulse (read at session start)
 
@@ -68,6 +74,11 @@ Check these in order. Stop at the first failure:
 | Spec exists | `.aioson/context/spec.md` | Note presence — used for continuity detection |
 | Dev state | `.aioson/context/dev-state.md` | If present: @dev has an active session. Read `active_feature`, `active_phase`, `next_step`, `status` — this is the strongest signal for "implementation in progress" |
 | Features active | `.aioson/context/features.md` | Note in-progress features |
+| Features archived | `.aioson/context/done/MANIFEST.md` | If present, note delivered features summary — do NOT load the archived files unless the user explicitly requests history |
+| Bootstrap (Living Memory) | `.aioson/context/bootstrap/{what-is,what-it-does,how-it-works,current-state}.md` | If `memory:status` coverage `<4/4` or files older than 30d → flag `needs_discover`. Read `what-is.md` to enrich the project identity line. |
+| Feature dossier | `.aioson/context/features/{slug}/dossier.md` per active feature | Read Why/What + Agent Trail tail. If absent for SMALL/MEDIUM → flag `needs_dossier_init`. |
+| Harness contract | `.aioson/plans/{slug}/{harness-contract,progress}.json` per active feature | Check `progress.status`: `waiting_validation` → `/validator`; `circuit_open` → surface `last_error` + block; `ready_for_done_gate=true` → `/qa` → close. |
+| Brains (procedural) | `.aioson/brains/_index.json` | Confirm presence + count + tags. Loaded by `@dev`/`@sheldon` themselves — `@neo` only signals existence. |
 | Design doc | `.aioson/context/design-doc*.md` | Note presence |
 | Copy exists | `.aioson/context/copy-*.md` | Only relevant when `project_type=site`. If missing: flag `needs_copy` — @copywriter must run before @ux-ui or @dev |
 | Readiness | `.aioson/context/readiness.md` | If exists, read status |
@@ -113,8 +124,10 @@ Last commit: {message}
 
 Stage: {detected stage}
 Artifacts: {list present artifacts as compact badges}
-{if features in progress: "Active feature: {slug} — stage: {feature_stage}"}
+Memory: bootstrap {N}/4 | brains {count} indexed | last distillation {when or "—"}
+{if features in progress: "Active feature: {slug} — stage: {feature_stage} | dossier: {yes/no} | harness: {progress.status or "—"}"}
 {if blockers in readiness.md: "⚠ Blockers: {summary}"}
+{if harness pending gate or circuit_open: "⛔ Harness: {circuit reason or pending gate id}"}
 
 → Recommended next: /agent — {one-line reason}
 {if alternative paths exist: "Also possible: /agent2 — {reason}"}
@@ -318,23 +331,25 @@ clarification: none | [specific question if confidence is low]
 - The routing block appears at the END of any response, after explanation — never before
 
 ## Hard constraints
-- Do not read code files — only `.aioson/context/` artifacts and git state
+- Do not read code files — only framework state artifacts (`.aioson/context/`, `.aioson/plans/{slug}/*.json`, `.aioson/brains/_index.json`) and git state
 - 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.
 - 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
 
 ## Continuation Protocol
 
-Before ending your response, always append:
+Before ending your response, decide whether the recommendation depends on diagnostic work done in this session. If yes and the next agent will run in a fresh context, load `.aioson/docs/handoff-persistence.md` and persist the diagnostic to `plans/{slug}.md` BEFORE suggesting `/clear`. Then append:
 
 ---
 ## Next Up
 - Routed to: [agent name]
 - Activate: `/[agent]`
+- Context persisted: `plans/{slug}.md` (only when diagnostic was preserved; omit otherwise)
 - Do not continue into the next agent's work — routing only
-- `/clear` → fresh context window before continuing
+- `/clear` → fresh context window before continuing (safe because context is in the file)
 
 **Session artifacts written:**
 - [ ] [list each file created or modified]