@jaimevalasek/aioson 1.20.0 → 1.21.3

package/src/i18n/messages/en.js

@@ -73,6 +73,18 @@ module.exports = {
       dry_run_summary: 'memory:restore [dry-run]: would move {source} → {dest}.',
       restored_success: 'memory:restore ✓ {kind} "{slug}" restored to {dest}.'
     },
+    help_memory_trim:
+      'aioson memory:trim [path] [--keep=<N>] [--archive=<path>] [--dry-run] [--json] [--locale=en]',
+    memory_trim: {
+      hook_blocked: 'memory:trim cannot be invoked from a runtime hook (tier-2 requires human action).',
+      no_current_state: 'memory:trim: {path} not found (nothing to trim).',
+      archive_path_escape: 'memory:trim: refused --archive outside the project: {path}',
+      section_not_found: 'memory:trim: "## What the system already has" section not found — nothing to do.',
+      nothing_to_archive: 'memory:trim: {kept} entries within keep={keep} window — nothing to archive.',
+      dry_run_summary: 'memory:trim [dry-run]: would archive {archived}/{total} entries (keep={keep}, active-slug exempt). {before_kb}KB → {after_kb}KB (saves {saved_kb}KB). No files written.',
+      notify_template: 'trimming current-state.md: archiving {archived} cold entries',
+      trimmed_success: 'memory:trim ✓ archived {archived} entries (kept {kept}). {before_kb}KB → {after_kb}KB. Archive: {archive}'
+    },
     memory_search: {
       query_empty: 'memory:search requires a non-empty query string.',
       query_too_long: 'memory:search query exceeds {max} characters.',
@@ -327,6 +339,7 @@ module.exports = {
     files_skipped: 'Files skipped: {count}',
     dry_run_header: '⚠  DRY RUN — no files were written. Showing what install would do:',
     dry_run_done_at: 'DRY RUN: nothing was written to {targetDir}',
+    gemini_deprecation_notice: '[DEPRECATED] Gemini CLI free/personal tier will be discontinued on 2026-06-18. Consider Codex or OpenCode for new projects. Enterprise (Code Assist Standard/Enterprise) continues to work.',
     dry_run_files_copied: 'Files that would be copied: {count}',
     dry_run_files_skipped: 'Files that would be skipped: {count}',
     next_steps: 'Next steps:',
@@ -399,6 +412,9 @@ module.exports = {
     context_conversation_language_format: '`conversation_language` is not a valid BCP-47 tag',
     context_conversation_language_format_hint: 'Use values like en, en-US, pt-BR.',
     node_version: 'Node.js >= 18 (current: {version})',
+    gemini_deprecation: 'Gemini CLI in use - free tier ends 2026-06-18 (enterprise unaffected)',
+    gemini_deprecation_hint:
+      'Run `aioson permissions-generator --tool=codex` (or --tool=opencode) to migrate. Enterprise (Code Assist Standard/Enterprise) keeps working; pre-existing .gemini/permissions.toml is preserved.',
     gateway_claude_pointer: 'CLAUDE gateway references shared AIOSON files',
     gateway_claude_pointer_hint:
       'Ensure CLAUDE.md references .aioson/config.md and .aioson/agents/setup.md.',

package/src/i18n/messages/es.js

@@ -74,6 +74,18 @@ module.exports = {
       dry_run_summary: 'memory:restore [dry-run]: movería {source} → {dest}.',
       restored_success: 'memory:restore ✓ {kind} "{slug}" restaurado a {dest}.'
     },
+    help_memory_trim:
+      'aioson memory:trim [ruta] [--keep=<N>] [--archive=<path>] [--dry-run] [--json] [--locale=es]',
+    memory_trim: {
+      hook_blocked: 'memory:trim no puede invocarse desde un hook de runtime (tier-2 requiere acción humana).',
+      no_current_state: 'memory:trim: {path} no encontrado (nada que recortar).',
+      archive_path_escape: 'memory:trim: --archive fuera del proyecto rechazado: {path}',
+      section_not_found: 'memory:trim: sección "## What the system already has" no encontrada — nada que hacer.',
+      nothing_to_archive: 'memory:trim: {kept} entradas dentro de la ventana keep={keep} — nada que archivar.',
+      dry_run_summary: 'memory:trim [dry-run]: archivaría {archived}/{total} entradas (keep={keep}, slug activo exento). {before_kb}KB → {after_kb}KB (ahorra {saved_kb}KB). No se escribió ningún archivo.',
+      notify_template: 'recortando current-state.md: archivando {archived} entradas frías',
+      trimmed_success: 'memory:trim ✓ {archived} entradas archivadas (conservadas {kept}). {before_kb}KB → {after_kb}KB. Archivo: {archive}'
+    },
     memory_search: {
       query_empty: 'memory:search requiere una consulta no vacía.',
       query_too_long: 'memory:search consulta supera {max} caracteres.',
@@ -198,6 +210,7 @@ module.exports = {
     files_skipped: 'Archivos omitidos: {count}',
     dry_run_header: '⚠  DRY RUN — no se escribio ningun archivo. Mostrando lo que haria el install:',
     dry_run_done_at: 'DRY RUN: no se escribio nada en {targetDir}',
+    gemini_deprecation_notice: '[DEPRECATED] El tier gratuito/personal de Gemini CLI se descontinuara el 2026-06-18. Considera Codex u OpenCode para nuevos proyectos. Enterprise (Code Assist Standard/Enterprise) sigue funcionando.',
     dry_run_files_copied: 'Archivos que se copiarian (would be copied): {count}',
     dry_run_files_skipped: 'Archivos que se omitirian (would be skipped): {count}',
     next_steps: 'Siguientes pasos:',
@@ -278,6 +291,9 @@ module.exports = {
     context_conversation_language_format: '`conversation_language` no es una etiqueta BCP-47 valida',
     context_conversation_language_format_hint: 'Usa valores como en, en-US, pt-BR.',
     node_version: 'Node.js >= 18 (actual: {version})',
+    gemini_deprecation: 'Gemini CLI en uso - el tier gratuito termina el 2026-06-18 (enterprise no afectado)',
+    gemini_deprecation_hint:
+      'Ejecuta `aioson permissions-generator --tool=codex` (o --tool=opencode) para migrar. Enterprise (Code Assist Standard/Enterprise) sigue funcionando; el .gemini/permissions.toml preexistente se conserva.',
     gateway_claude_pointer: 'El gateway de CLAUDE referencia archivos compartidos de AIOSON',
     gateway_claude_pointer_hint:
       'Asegura que CLAUDE.md referencie .aioson/config.md y .aioson/agents/setup.md.',

package/src/i18n/messages/fr.js

@@ -74,6 +74,18 @@ module.exports = {
       dry_run_summary: 'memory:restore [dry-run] : déplacerait {source} → {dest}.',
       restored_success: 'memory:restore ✓ {kind} « {slug} » restauré vers {dest}.'
     },
+    help_memory_trim:
+      'aioson memory:trim [chemin] [--keep=<N>] [--archive=<path>] [--dry-run] [--json] [--locale=fr]',
+    memory_trim: {
+      hook_blocked: 'memory:trim ne peut pas être invoqué depuis un hook de runtime (tier-2 exige une action humaine).',
+      no_current_state: 'memory:trim : {path} introuvable (rien à élaguer).',
+      archive_path_escape: 'memory:trim : --archive hors du projet refusé : {path}',
+      section_not_found: 'memory:trim : section "## What the system already has" introuvable — rien à faire.',
+      nothing_to_archive: 'memory:trim : {kept} entrées dans la fenêtre keep={keep} — rien à archiver.',
+      dry_run_summary: 'memory:trim [dry-run] : archiverait {archived}/{total} entrées (keep={keep}, slug actif exempté). {before_kb}KB → {after_kb}KB (économise {saved_kb}KB). Aucun fichier écrit.',
+      notify_template: 'élagage de current-state.md : archivage de {archived} entrées froides',
+      trimmed_success: 'memory:trim ✓ {archived} entrées archivées (conservées {kept}). {before_kb}KB → {after_kb}KB. Archive : {archive}'
+    },
     memory_search: {
       query_empty: 'memory:search exige une requête non-vide.',
       query_too_long: 'memory:search requête dépasse {max} caractères.',
@@ -198,6 +210,7 @@ module.exports = {
     files_skipped: 'Fichiers ignores : {count}',
     dry_run_header: '⚠  DRY RUN — aucun fichier ecrit. Apercu de ce que install ferait :',
     dry_run_done_at: 'DRY RUN : rien n a ete ecrit dans {targetDir}',
+    gemini_deprecation_notice: '[DEPRECATED] Le palier gratuit/personnel de Gemini CLI sera supprime le 2026-06-18. Envisagez Codex ou OpenCode pour les nouveaux projets. Enterprise (Code Assist Standard/Enterprise) continue de fonctionner.',
     dry_run_files_copied: 'Fichiers qui seraient copies (would be copied) : {count}',
     dry_run_files_skipped: 'Fichiers qui seraient ignores (would be skipped) : {count}',
     next_steps: 'Etapes suivantes :',
@@ -277,6 +290,9 @@ module.exports = {
     context_conversation_language_format: '`conversation_language` n est pas une balise BCP-47 valide',
     context_conversation_language_format_hint: 'Utilisez des valeurs comme en, en-US, pt-BR.',
     node_version: 'Node.js >= 18 (actuel : {version})',
+    gemini_deprecation: 'Gemini CLI utilise - le palier gratuit se termine le 2026-06-18 (enterprise non affecte)',
+    gemini_deprecation_hint:
+      'Lancez `aioson permissions-generator --tool=codex` (ou --tool=opencode) pour migrer. Enterprise (Code Assist Standard/Enterprise) continue de fonctionner; le .gemini/permissions.toml preexistant est conserve.',
     gateway_claude_pointer: 'La passerelle CLAUDE reference les fichiers partages AIOSON',
     gateway_claude_pointer_hint:
       'Assurez-vous que CLAUDE.md reference .aioson/config.md et .aioson/agents/setup.md.',

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

@@ -74,6 +74,18 @@ module.exports = {
       dry_run_summary: 'memory:restore [dry-run]: moveria {source} → {dest}.',
       restored_success: 'memory:restore ✓ {kind} "{slug}" restaurado para {dest}.'
     },
+    help_memory_trim:
+      'aioson memory:trim [caminho] [--keep=<N>] [--archive=<path>] [--dry-run] [--json] [--locale=pt-BR]',
+    memory_trim: {
+      hook_blocked: 'memory:trim não pode ser invocado por um hook de runtime (tier-2 exige ação humana).',
+      no_current_state: 'memory:trim: {path} não encontrado (nada a aparar).',
+      archive_path_escape: 'memory:trim: --archive fora do projeto recusado: {path}',
+      section_not_found: 'memory:trim: seção "## What the system already has" não encontrada — nada a fazer.',
+      nothing_to_archive: 'memory:trim: {kept} entradas dentro da janela keep={keep} — nada a arquivar.',
+      dry_run_summary: 'memory:trim [dry-run]: arquivaria {archived}/{total} entradas (keep={keep}, slug ativo isento). {before_kb}KB → {after_kb}KB (economiza {saved_kb}KB). Nenhum arquivo escrito.',
+      notify_template: 'aparando current-state.md: arquivando {archived} entradas frias',
+      trimmed_success: 'memory:trim ✓ {archived} entradas arquivadas (mantidas {kept}). {before_kb}KB → {after_kb}KB. Arquivo: {archive}'
+    },
     memory_search: {
       query_empty: 'memory:search requer uma consulta não-vazia.',
       query_too_long: 'memory:search consulta excede {max} caracteres.',
@@ -292,6 +304,7 @@ module.exports = {
     files_skipped: 'Arquivos ignorados: {count}',
     dry_run_header: '⚠  DRY RUN — nenhum arquivo foi escrito. Mostrando o que o install faria:',
     dry_run_done_at: 'DRY RUN: nada foi escrito em {targetDir}',
+    gemini_deprecation_notice: '[DEPRECATED] O tier free/pessoal do Gemini CLI sera descontinuado em 2026-06-18. Considere Codex ou OpenCode para novos projetos. Enterprise (Code Assist Standard/Enterprise) continua funcionando.',
     dry_run_files_copied: 'Arquivos que seriam copiados (would be copied): {count}',
     dry_run_files_skipped: 'Arquivos que seriam ignorados (would be skipped): {count}',
     next_steps: 'Proximos passos:',
@@ -372,6 +385,9 @@ module.exports = {
       '`conversation_language` nao e uma tag BCP-47 valida',
     context_conversation_language_format_hint: 'Use valores como en, en-US, pt-BR.',
     node_version: 'Node.js >= 18 (atual: {version})',
+    gemini_deprecation: 'Gemini CLI em uso - tier free encerra em 2026-06-18 (enterprise nao afetado)',
+    gemini_deprecation_hint:
+      'Rode `aioson permissions-generator --tool=codex` (ou --tool=opencode) para migrar. Enterprise (Code Assist Standard/Enterprise) continua funcionando; .gemini/permissions.toml pre-existente e preservado.',
     gateway_claude_pointer: 'Gateway do CLAUDE referencia arquivos compartilhados do AIOSON',
     gateway_claude_pointer_hint:
       'Garanta que CLAUDE.md referencie .aioson/config.md e .aioson/agents/setup.md.',

package/src/install-wizard.js

@@ -6,7 +6,7 @@ const { getCliVersionSync } = require('./version');
 const TOOLS = [
   { id: 'claude',    label: 'Claude Code',    desc: 'Slash commands, CLAUDE.md, .claude/' },
   { id: 'codex',    label: 'Codex (OpenAI)', desc: 'AGENTS.md protocol' },
-  { id: 'gemini',   label: 'Gemini CLI',     desc: 'GEMINI.md + .gemini/commands/' },
+  { id: 'gemini',   label: 'Gemini CLI',     desc: 'GEMINI.md + .gemini/commands/', deprecated: true },
   { id: 'opencode', label: 'OpenCode',       desc: 'OPENCODE.md protocol' }
 ];
 
@@ -112,7 +112,8 @@ function renderScreen1(cursor, selected, warn, stdout) {
     const tool    = TOOLS[i];
     const pointer = i === cursor ? '►' : ' ';
     const check   = selected.has(tool.id) ? '✓' : ' ';
-    stdout.write(`  ${pointer} [${check}] ${tool.label.padEnd(20)} ${tool.desc}\n`);
+    const deprNote = tool.deprecated ? '  ⚠ [DEPRECATED] free tier ends 2026-06-18' : '';
+    stdout.write(`  ${pointer} [${check}] ${tool.label.padEnd(20)} ${tool.desc}${deprNote}\n`);
   }
   if (warn) stdout.write('\n  ⚠  Select at least one tool to continue.\n');
   stdout.write('\n');

package/src/lib/tool-capabilities.js

@@ -5,11 +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 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.
+// 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 = {
@@ -18,50 +18,53 @@ 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'],
-    supports_yolo: true,
-    yolo_args: ['--dangerously-skip-permissions'],
-  },
-  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'],
-    supports_yolo: true,
-    yolo_args: ['--dangerously-bypass-approvals-and-sandbox'],
-  },
-  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,
-    supports_yolo: false,
-    yolo_args: null,
-  },
-  gemini: {
+    supports_session_id: true,
+    resume_session_id: ['--session', '<id>'],
+    supports_session_picker: false,
+    session_picker: null,
+    supports_yolo: false,
+    yolo_args: null,
+  },
+  // DEPRECATED: Gemini CLI free/personal tier ends 2026-06-18. Enterprise
+  // (Code Assist Standard/Enterprise) unaffected. Hard removal in v1.22.
+  // See gemini-phaseout / CHANGELOG v1.21.x.
+  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_yolo: false,
-    yolo_args: 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();
@@ -80,7 +83,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 [];
   }
@@ -101,29 +104,29 @@ function resolveResumeArgs(tool, resumeOpt) {
   }
 
   return Array.isArray(caps.resume_last) ? [...caps.resume_last] : [];
-}
-
-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,
-};
+}
+
+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/memory-reflect-engine.js

@@ -248,12 +248,18 @@ async function buildPrompt({ targetDir, agent, evaluation, sessionId }) {
 
 function buildInstructions(targets) {
   const names = targets.map((t) => `bootstrap/${t}`).join(', ');
-  return [
+  const parts = [
     `Edit only: ${names}.`,
     'Remove obsolete entries. Add new capabilities. Preserve YAML frontmatter.',
-    'Update the `generated_at` field in each touched file.',
-    'When done, write the result via `aioson memory:reflect-commit` (do not edit other files).'
-  ].join(' ');
+    'Update the `generated_at` field in each touched file.'
+  ];
+  if (targets.includes('current-state.md')) {
+    // Tag entries so the feature:close / memory:trim rollup can attribute and
+    // date them (agent-loading-contract P0).
+    parts.push('In current-state.md, prefix each new entry under "## What the system already has" with `[{feature-slug} · {YYYY-MM-DD}]`.');
+  }
+  parts.push('When done, write the result via `aioson memory:reflect-commit` (do not edit other files).');
+  return parts.join(' ');
 }
 
 function hasFrontmatter(text) {

package/src/permissions-generator.js

@@ -195,6 +195,9 @@ function tomlString(value) {
 function buildGeminiToml({ shellPatterns, aiosonCommands, denyShellPatterns = [], denyAiosonCommands = [] }, tool) {
   const lines = [];
   lines.push('# Generated by aioson permissions-generator. Do not edit by hand.');
+  lines.push('# WARNING: Gemini CLI free tier ends 2026-06-18. This file remains');
+  lines.push('# functional for enterprise users (Code Assist Standard/Enterprise).');
+  lines.push('# See AIOSON CHANGELOG v1.21.x for migration guidance.');
   lines.push('version = "1.1"');
   lines.push(`mode = ${tomlString(tool.mode || 'guarded')}`);
   lines.push(`requires_tty = ${Boolean(tool.requires_tty)}`);

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

@@ -33,6 +33,8 @@ Also read when present:
 
 This gives you full semantic understanding of the system without reading the codebase directly.
 
+> `current-state.md` is the **hot log** (recent + active-feature entries only). Older shipped capabilities are in `current-state-archive.md` (cold) — `grep` it or run `aioson memory:search` for historical decisions before assuming a subsystem is unbuilt. Never load the archive at activation. See `.aioson/design-docs/agent-loading-contract.md`.
+
 ## Feature dossier
 
 Before loading per-slug PRD/spec, check `.aioson/context/features/{slug}/dossier.md`. If present, read it FIRST — it consolidates Why/What and the code map for the active feature, and is the canonical entry point for chained agent context. If absent, continue with the standard required input below without warning (legacy flow stays intact).
@@ -145,6 +147,7 @@ Action: /pm or /dev
 - If a decision is deferred, document why.
 - If `readiness.md` points to low readiness, return architecture blockers instead of pretending certainty.
 - Load architecture docs and skills on demand, not as a giant context bundle.
+- For maintainability / performance / componentization assessment of existing code, load the shared lens `.aioson/docs/quality/code-health-analysis.md` on demand.
 
 ## Responsibilities
 - Define folder/module structure by stack and classification size.

package/template/.aioson/agents/committer.md

@@ -146,7 +146,7 @@ type(scope): short description in imperative mood
    - run `aioson git:guard . --json` again immediately before commit
    - if still safe, execute the commit
    - if not safe, stop and explain why
-   - **after a successful commit**: if `.aioson/context/bootstrap/current-state.md` exists, append one line under `## What the system already has` summarizing what the commit added (use the commit subject — keep append-only, never replace); then delete `.aioson/context/commit-prep.json` so it is never reused accidentally
+   - **after a successful commit**: if `.aioson/context/bootstrap/current-state.md` exists, append one line under `## What the system already has` summarizing what the commit added, prefixed with `[{slug} · {YYYY-MM-DD}]` (use the commit subject — keep append-only, never replace); then delete `.aioson/context/commit-prep.json` so it is never reused accidentally
 4. If the user does **not** approve the draft, do **not** delete `commit-prep.json` — keep it for the next attempt.
 
 ## Observability

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

@@ -48,7 +48,7 @@ Read `.aioson/context/dev-state.md` if it exists.
 
 **dev-state.md NOT found (cold start):**
 - Read only: `project.context.md` + `features.md` (if present). Stop there.
-- **Bootstrap:** read `bootstrap/how-it-works.md` + `bootstrap/current-state.md` if present.
+- **Bootstrap:** read `bootstrap/how-it-works.md` + `bootstrap/current-state.md` (hot log) if present. Older shipped work is in `bootstrap/current-state-archive.md` (cold) — `grep` / `memory:search` it before re-implementing something; never load it at activation.
 - Ask what feature/task to work on.
 - Run `aioson memory:summary . --last=5`, then `aioson context:pack . --agent=dev --goal="<goal>"`.
 - Tags: run `aioson brain:query . --tags=<tags> --min-quality=4`.
@@ -241,7 +241,7 @@ These rules apply even if no extra dev doc was loaded:
 5. Run the actual verification command before marking any step done
 6. Keep `skeleton-system.md` current when files materially change
 7. If repeated debugging stalls, load the debugging protocol instead of guessing
-8. After a significant slice or phase lands, append one line to `.aioson/context/bootstrap/current-state.md` under `## What the system already has` describing the new capability. Append-only; never replace existing entries. Skip if `bootstrap/` does not exist.
+8. After a significant slice or phase lands, append one line to `.aioson/context/bootstrap/current-state.md` under `## What the system already has` describing the new capability, prefixed with `[{slug} · {YYYY-MM-DD}]` so it can be archived precisely later. Append-only; never replace existing entries. Skip if `bootstrap/` does not exist.
 
 ## Motor AIOSON — hardening rules (must respect)
 

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

@@ -24,7 +24,7 @@ Beyond the bootstrap gate, `@deyvin` operates with 9 memory layers. Load each **
 
 | Layer | Path | When to consult |
 |-------|------|-----------------|
-| Bootstrap (Living Memory) | `.aioson/context/bootstrap/*.md` | Always — first, before reasoning |
+| Bootstrap (Living Memory) | `.aioson/context/bootstrap/*.md` | Always — first, before reasoning. `current-state.md` is the hot log; `current-state-archive.md` is cold (grep / `memory:search` on demand, never at activation) — see `.aioson/design-docs/agent-loading-contract.md` |
 | Project pulse | `.aioson/context/project-pulse.md` | Session start; learn last agent + active feature + blockers |
 | Dev-state | `.aioson/context/dev-state.md` | If a feature is in progress (continuity case) |
 | Feature dossier | `.aioson/context/features/{slug}/dossier.md` | If a feature slug is known — Why/What + code map |
@@ -77,6 +77,7 @@ The detailed pair-programming protocol is split into on-demand framework docs:
 - `.aioson/docs/deyvin/pair-execution.md`
 - `.aioson/docs/deyvin/runtime-handoffs.md`
 - `.aioson/docs/deyvin/debugging-escalation.md`
+- `.aioson/docs/quality/code-health-analysis.md` (shared improvement lens — apply to a slice; escalate if the analysis spans the whole system)
 
 ## Deterministic preflight
 

package/template/.aioson/agents/pentester.md

@@ -285,6 +285,7 @@ The framework playbooks above cover the AIOSON-internal review surface. For app-
 
 | Doc | Load when |
 |---|---|
+| `.aioson/docs/quality/code-health-analysis.md` | Tracing the **execution chain** of a sensitive flow, or judging where test/regression coverage of an attack-relevant path is weak — shared improvement lens (coverage · regression · execution-chain · perf · componentization) |
 | `.aioson/docs/pentester/app-playbooks.md` | `review_contract.target_mode = app_target` — full step-by-step methodology for TS-A01..A07 with OWASP ASVS 5.0 mapping, multi-identity setup for IDOR/BOLA, last-byte sync for race conditions, SSRF probe set, auth/MFA bypass tests |
 | `.aioson/docs/pentester/browser-dast-playbook.md` | `review_contract.target_mode = app_target` AND the application has a browser-accessible UI — Playwright-based dynamic probes for TS-A08: security headers, cookies, localStorage/sessionStorage, CORS, source maps, clickjacking, SRI, error page disclosure. **Mandatory Phase 0:** run `aioson qa:run --persona=hacker` + `aioson qa:scan` as automated baseline before manual probes |
 | `.aioson/docs/pentester/llm-supplychain.md` | Feature touches LLM prompts, RAG, tool invocation, `package.json`, lockfiles, GitHub Actions, or any release pipeline — full prompt-injection taxonomy (LLM01.1/.2/.3), supply-chain incidents, SAST/DAST/secrets tool catalog, SLSA + Sigstore |

package/template/.aioson/agents/qa.md

@@ -26,6 +26,8 @@ If `.aioson/context/bootstrap/` exists, read these files before starting review:
 - `.aioson/context/bootstrap/what-is.md` — system identity and current state
 - `.aioson/context/bootstrap/current-state.md` — capabilities already shipped (so the review does not flag implemented features as missing or scope-creep recently-landed work)
 
+> `current-state.md` is the **hot log** (recent + active-feature entries only). Older shipped capabilities are in `current-state-archive.md` (cold) — `grep` it or run `aioson memory:search` before flagging a capability as missing/unbuilt. Never load the archive at activation. See `.aioson/design-docs/agent-loading-contract.md`.
+
 Use this knowledge to evaluate the feature in the context of the system around it, not in isolation. Skip silently when `bootstrap/` is absent.
 
 **Bootstrap gate (Living Memory):** before starting, run `aioson memory:status .` if available. If `Bootstrap < 4/4` or the files are older than 30 days, surface a warning at the top of your QA report:
@@ -169,6 +171,8 @@ When AIOSON CLI is available and feature mode is MEDIUM, prefer the tracked invo
 3. **Write missing tests** — for Critical/High findings, write the test. Do not just describe it.
 4. **Deliver report** — ordered by severity, each finding: location + risk + fix.
 
+> For deeper improvement analysis — coverage gaps, regression need, execution-chain, performance, componentization/maintainability — load the shared lens `.aioson/docs/quality/code-health-analysis.md` on demand (routes coverage→@tester, structure/perf→@architect).
+
 ## Risk-first checklist
 
 ### Business rules

package/template/.aioson/agents/sheldon.md

@@ -214,6 +214,7 @@ The detailed Sheldon protocol is split into on-demand framework docs:
 - `.aioson/docs/sheldon/web-intelligence.md`
 - `.aioson/docs/sheldon/quality-lens.md`
 - `.aioson/docs/sheldon/enrichment-paths.md`
+- `.aioson/docs/quality/code-health-analysis.md` (shared improvement lens — coverage · regression · execution-chain · performance · componentization/maintainability)
 
 ## Deterministic preflight
 

package/template/.aioson/agents/tester.md

@@ -456,6 +456,8 @@ Run the security regression tests. If any fail, it means the fix is incomplete
 
 Don't auto-load. Add only when the trigger fires. Full details: `.aioson/docs/tester/coverage-quality.md` § 6.
 
+> Scoping **where** the code needs more/better tests, a regression guard, or tracing the execution chain before writing them? Load the shared improvement lens `.aioson/docs/quality/code-health-analysis.md` (plan → investigate → refine → operate → test → adjust).
+
 | Layer | Trigger | Tooling |
 |---|---|---|
 | Snapshot | Stable UI/DOM/JSON output | vitest/jest snapshots; sanitize timestamps + IDs first |

package/template/.aioson/config/autonomy-protocol.json

@@ -45,6 +45,7 @@
         "memory:refresh",
         "memory:archive",
         "memory:restore",
+        "memory:trim",
         "workflow:next",
         "workflow:heal",
         "live:handoff",