@jaimevalasek/aioson 1.21.0 → 1.21.4

package/CHANGELOG.md

@@ -4,7 +4,32 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
-## [1.21.0] - 2026-06-XX
+## [1.21.3] - 2026-05-28
+
+### Security
+- **`memory:trim --archive=<path>` is now contained under the project root (TS-LC-01).** It was resolved relative to `cwd` with no containment, so a crafted/typo'd path could write or overwrite a file outside the project. Now resolved under the project root and rejected with `archive_path_escape` on absolute or `..`-traversal escape — mirroring the containment wall in `memory-reflect-commit`. Localized message added in all 4 locales.
+- **`feature:close` auto-trim hook now honors `AIOSON_RUNTIME_HOOK` (TS-LC-02).** The hook called the trim engine directly, bypassing the hook-context guard that `memory:trim` enforces. It now skips when running in a hook/automation context, so a tier-2 memory mutation never fires outside explicit human action.
+
+### Tests
+- Coverage pass over the v1.21.2 agent-loading-contract code (`node --test --experimental-test-coverage`): `current-state-trim.js` 98.8%→100% line, `memory-trim.js` 73.9%→88.6% line / 64.4%→76.7% branch. Adds error/edge-path tests (`no_current_state`, `section_not_found`, custom/escaping `--archive`, headerless archive, hook skip paths) and verifies all `cli.memory_{archive,restore,search}` keys resolve.
+
+## [1.21.2] - 2026-05-28
+
+### Added
+- **Agent loading contract + `memory:trim`.** `bootstrap/current-state.md` is an append-only log that every implementation/review agent read in full at activation (~81KB / ~33k tokens, 84% of the bootstrap). New `aioson memory:trim [--keep=<N>] [--archive=<path>] [--dry-run] [--json]` splits its "## What the system already has" section into a HOT log + a cold `current-state-archive.md` (entries MOVED verbatim, never deleted; active-feature entries exempt). `feature:close` (PASS) auto-rolls aged entries (`--no-trim` to opt out). New governance doc `.aioson/design-docs/agent-loading-contract.md` defines the three loading tiers + retention policy. The repo's own current-state was trimmed 81KB → 21KB.
+- **`context:health` now measures `bootstrap/*.md`** — the per-activation layer it previously ignored — and excludes the cold `*-archive.md`; a heavy `current-state.md` now points to `memory:trim`.
+- **Shared code-health analysis lens** `.aioson/docs/quality/code-health-analysis.md` (plan → investigate → refine → operate → test → adjust over coverage, test sufficiency, regression need, execution-chain, performance, componentization), wired on-demand into `@tester`/`@qa`/`@pentester`/`@architect`/`@sheldon`/`@deyvin`.
+- **Current-state entry tagging** — the reflect engine, `@dev`, and `@committer` now prefix new entries with `[{slug} · {YYYY-MM-DD}]` for precise rollup; `@qa`/`@architect`/`@dev`/`@deyvin` bootstrap sections gained archive-awareness (grep the archive before flagging a capability as missing).
+
+### Fixed
+- **`memory:archive` / `memory:restore` / `memory:search` logged raw i18n keys** in every locale — they called message keys without the required `cli.` namespace prefix, so `t()` missed and echoed the key (e.g. `memory_archive.id_required`). All 25 calls now use the `cli.` prefix and localize correctly.
+
+## [1.21.1] - 2026-06-XX
+
+### Fixed
+- **`memory:reflect-commit --dry-run` is now non-destructive.** The command never read the `--dry-run` flag, so a "dry run" silently performed the full destructive commit — it wrote the bootstrap files **and** unlinked the single-use manifest, leaving the flow unrecoverable (`missing_manifest`) on the next call. `--dry-run` now runs validation + path containment exactly like a real commit, then returns `{ ok: true, dryRun: true, would_write: [...] }` without writing any file or consuming the manifest, so a real commit can still follow. Regression coverage in `tests/memory-reflect-commit-dry-run.test.js`. Note: the reflect manifest remains single-use — a successful real commit consumes it (re-run by re-running `memory:reflect-prepare`).
+
+## [1.21.0] - 2026-05-28
 
 ### Added
 - **Gemini CLI deprecation warning (gemini-phaseout Phase 1).** Google announced (2026-05-20) that the Gemini CLI free/personal tier ends 2026-06-18.

package/docs/pt/living-memory/reflexao-in-harness.md

@@ -121,6 +121,8 @@ O agente é livre para usar o LLM como achar melhor para fazer a reescrita. O CL
 
 Se tudo passa: escreve, apaga o manifest, emite `memory_reflect_committed` em runtime. Se falha: emite `memory_reflect_failed` com a lista de erros e o agente tem 1 retry.
 
+> **`--dry-run` (pré-visualização não-destrutiva):** `aioson memory:reflect-commit . --agent=dev --output=<json> --dry-run` roda a validação + containment de path exatamente como o commit real, mas **não escreve nada e não consome o manifest** — retorna `{ ok: true, dryRun: true, would_write: [...] }`. Use pra conferir o output antes de aplicar. Atenção: o manifest é **single-use** — um commit real (sem `--dry-run`) o apaga; pra recomeçar, rode `memory:reflect-prepare` de novo.
+
 ## Exemplo end-to-end
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.21.0",
+  "version": "1.21.4",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/agents.js

@@ -29,14 +29,15 @@ function buildAgentPrompt(agent, tool, options = {}) {
   const safeTool = String(tool || 'codex').toLowerCase();
   const instructionPath = options.instructionPath || agent.path;
   const targetDir = options.targetDir ? String(options.targetDir) : '.';
-  const interactionLanguage = String(options.interactionLanguage || 'en');
-  const autonomyMode = String(options.autonomyMode || '').trim();
-  const capabilitySummary = String(options.capabilitySummary || '').trim();
-  const activationContext = String(options.activationContext || '').trim();
-  const dependencyText =
-    agent.dependsOn.length > 0
-      ? `Check required context files first: ${agent.dependsOn.join(', ')}.`
-      : 'No prerequisite context files are required.';
+  const interactionLanguage = String(options.interactionLanguage || 'en');
+  const autonomyMode = String(options.autonomyMode || '').trim();
+  const capabilitySummary = String(options.capabilitySummary || '').trim();
+  const activationContext = String(options.activationContext || '').trim();
+  const dependsOn = Array.isArray(options.dependsOn) ? options.dependsOn : agent.dependsOn;
+  const dependencyText =
+    dependsOn.length > 0
+      ? `Check required context files first: ${dependsOn.join(', ')}.`
+      : 'No prerequisite context files are required.';
   const activationBlock = activationContext
     ? [
       '',
@@ -68,20 +69,20 @@ function buildAgentPrompt(agent, tool, options = {}) {
     `**Scope boundary:** You operate exclusively as ${agent.command}. Do not perform work that belongs to another agent. When your work is complete, output only the handoff — which agent is next and why. Do not continue into that agent\'s territory.`,
   ].join('\n');
 
-  if (safeTool === 'claude') {
-    return `Read ${instructionPath} and execute ${agent.command}. ${dependencyText}${activationBlock} Write output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
-  }
-
-  if (safeTool === 'gemini') {
-    return `Run the Gemini command mapped to ${instructionPath} and execute ${agent.command}. ${dependencyText}${activationBlock} Save result to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
-  }
-
-  if (safeTool === 'opencode') {
-    return `Use agent "${agent.id}" from ${instructionPath}. ${dependencyText}${activationBlock} Save output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
-  }
-
-  return `Read AGENTS.md and execute ${agent.command} using ${instructionPath}. ${dependencyText}${activationBlock} Save output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
-}
+  if (safeTool === 'claude') {
+    return `Read ${instructionPath} and execute ${agent.command}. ${dependencyText}${activationBlock}\n\nWrite output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
+  }
+
+  if (safeTool === 'gemini') {
+    return `Run the Gemini command mapped to ${instructionPath} and execute ${agent.command}. ${dependencyText}${activationBlock}\n\nSave result to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
+  }
+
+  if (safeTool === 'opencode') {
+    return `Use agent "${agent.id}" from ${instructionPath}. ${dependencyText}${activationBlock}\n\nSave output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
+  }
+
+  return `Read AGENTS.md and execute ${agent.command} using ${instructionPath}. ${dependencyText}${activationBlock}\n\nSave output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
+}
 
 module.exports = {
   normalizeAgentName,

package/src/cli.js

@@ -18,6 +18,7 @@ const { runChainAudit } = require('./commands/chain-audit');
 const { runMemorySearch } = require('./commands/memory-search');
 const { runMemoryArchive } = require('./commands/memory-archive');
 const { runMemoryRestore } = require('./commands/memory-restore');
+const { runMemoryTrim } = require('./commands/memory-trim');
 const { runSetupContext } = require('./commands/setup-context');
 const { runLocaleApply } = require('./commands/locale-apply');
 const { runSmokeTest } = require('./commands/smoke');
@@ -57,6 +58,8 @@ const { runSquadStatus } = require('./commands/squad-status');
 const { runSquadDoctor } = require('./commands/squad-doctor');
 const { runSquadRepairGenomes } = require('./commands/squad-repair-genomes');
 const { runSquadValidate } = require('./commands/squad-validate');
+const { runSquadRoleScan } = require('./commands/squad-role-scan');
+const { runSquadPlaybook } = require('./commands/squad-playbook');
 const { runSquadExport } = require('./commands/squad-export');
 const { runSquadPipeline } = require('./commands/squad-pipeline');
 const { runSquadAgentCreate } = require('./commands/squad-agent-create');
@@ -79,10 +82,12 @@ const { runSquadWebhook } = require('./commands/squad-webhook');
 const { runSquadBus } = require('./commands/squad-bus');
 const { runSquadAutorun } = require('./commands/squad-autorun');
 const { runSquadDependencyGraph } = require('./commands/squad-dependency-graph');
-const { runSquadToolRegister } = require('./commands/squad-tool-register');
-const { runSquadReview } = require('./commands/squad-review');
-const { runAgentAudit } = require('./commands/agent-audit');
-const { runBriefGen } = require('./commands/brief-gen');
+const { runSquadToolRegister } = require('./commands/squad-tool-register');
+const { runSquadReview } = require('./commands/squad-review');
+const { runAgentAudit } = require('./commands/agent-audit');
+const { runSkillAudit } = require('./commands/skill-audit');
+const { runQualityAudit } = require('./commands/quality-audit');
+const { runBriefGen } = require('./commands/brief-gen');
 const { runHarnessInit, runHarnessValidate, runHarnessApplyValidation } = require('./commands/harness');
 const { runVerifyGate } = require('./commands/verify-gate');
 const {
@@ -324,6 +329,10 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'squad-repair-genomes',
   'squad:validate',
   'squad-validate',
+  'squad:role-scan',
+  'squad-role-scan',
+  'squad:playbook',
+  'squad-playbook',
   'squad:export',
   'squad-export',
   'squad:pipeline',
@@ -375,9 +384,13 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'squad-tool-register',
   'squad:review',
   'squad-review',
-  'agent:audit',
-  'agent-audit',
-  'brief:gen',
+  'agent:audit',
+  'agent-audit',
+  'skill:audit',
+  'skill-audit',
+  'quality:audit',
+  'quality-audit',
+  'brief:gen',
   'harness:init',
   'harness-init',
   'harness:validate',
@@ -525,6 +538,8 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'memory-archive',
   'memory:restore',
   'memory-restore',
+  'memory:trim',
+  'memory-trim',
   'memory:reflect-prepare',
   'memory-reflect-prepare',
   'memory:reflect-commit',
@@ -809,9 +824,11 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_squad_daemon');
   logHelpLine(t, logger, 'cli.help_squad_mcp');
   logHelpLine(t, logger, 'cli.help_squad_roi');
-  logHelpLine(t, logger, 'cli.help_squad_score');
-  logHelpLine(t, logger, 'cli.help_squad_learning');
-  logHelpLine(t, logger, 'cli.help_learning');
+  logHelpLine(t, logger, 'cli.help_squad_score');
+  logHelpLine(t, logger, 'cli.help_squad_learning');
+  logHelpLine(t, logger, 'cli.help_agent_audit');
+  logHelpLine(t, logger, 'cli.help_quality_audit');
+  logHelpLine(t, logger, 'cli.help_learning');
   logHelpLine(t, logger, 'cli.help_runtime_init');
   logHelpLine(t, logger, 'cli.help_runtime_ingest');
   logHelpLine(t, logger, 'cli.help_runtime_task_start');
@@ -834,9 +851,10 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_scaffold_complete');
   logHelpLine(t, logger, 'cli.help_runtime_backup');
   logHelpLine(t, logger, 'cli.help_runtime_restore');
-  logHelpLine(t, logger, 'cli.help_skill_install');
-  logHelpLine(t, logger, 'cli.help_skill_list');
-  logHelpLine(t, logger, 'cli.help_skill_remove');
+  logHelpLine(t, logger, 'cli.help_skill_install');
+  logHelpLine(t, logger, 'cli.help_skill_list');
+  logHelpLine(t, logger, 'cli.help_skill_remove');
+  logHelpLine(t, logger, 'cli.help_skill_audit');
   logHelpLine(t, logger, 'cli.help_design_hybrid_options');
   logHelpLine(t, logger, 'cli.help_cloud_import_squad');
   logHelpLine(t, logger, 'cli.help_cloud_import_genome');
@@ -1161,6 +1179,10 @@ async function main() {
       result = await runSquadRepairGenomes({ args, options, logger: commandLogger, t });
     } else if (command === 'squad:validate' || command === 'squad-validate') {
       result = await runSquadValidate({ args, options, logger: commandLogger, t });
+    } else if (command === 'squad:role-scan' || command === 'squad-role-scan') {
+      result = await runSquadRoleScan({ args, options, logger: commandLogger });
+    } else if (command === 'squad:playbook' || command === 'squad-playbook') {
+      result = await runSquadPlaybook({ args, options, logger: commandLogger });
     } else if (command === 'squad:export' || command === 'squad-export') {
       result = await runSquadExport({ args, options, logger: commandLogger, t });
     } else if (command === 'squad:pipeline' || command === 'squad-pipeline') {
@@ -1213,10 +1235,14 @@ async function main() {
       result = await runSquadToolRegister({ args, options, logger: commandLogger });
     } else if (command === 'squad:review' || command === 'squad-review') {
       result = await runSquadReview({ args, options, logger: commandLogger });
-    } else if (command === 'agent:audit' || command === 'agent-audit') {
-      result = await runAgentAudit({ args, options, logger: commandLogger });
-    } else if (command === 'brief:gen' || command === 'brief-gen') {
-      result = await runBriefGen({ args, options, logger: commandLogger, t });
+    } else if (command === 'agent:audit' || command === 'agent-audit') {
+      result = await runAgentAudit({ args, options, logger: commandLogger });
+    } else if (command === 'skill:audit' || command === 'skill-audit') {
+      result = await runSkillAudit({ args, options, logger: commandLogger });
+    } else if (command === 'quality:audit' || command === 'quality-audit') {
+      result = await runQualityAudit({ args, options, logger: commandLogger });
+    } else if (command === 'brief:gen' || command === 'brief-gen') {
+      result = await runBriefGen({ args, options, logger: commandLogger, t });
     } else if (command === 'harness:init' || command === 'harness-init') {
       result = await runHarnessInit({ args, options, logger: commandLogger, t });
     } else if (command === 'harness:validate' || command === 'harness-validate') {
@@ -1265,9 +1291,9 @@ async function main() {
       result = await runSpecCheckpoint({ args, options, logger: commandLogger });
     } else if (command === 'spec:tasks' || command === 'spec-tasks') {
       result = await runSpecTasks({ args, options, logger: commandLogger });
-    } else if (command.startsWith('learning:') || command === 'learning') {
-      const sub = command === 'learning' ? (args[1] || 'list') : command.split(':')[1];
-      result = await runLearning({ args, options: { ...options, sub }, logger: commandLogger, t });
+    } else if (command.startsWith('learning:') || command === 'learning') {
+      const sub = command === 'learning' ? (options.sub || args[1] || 'list') : command.split(':')[1];
+      result = await runLearning({ args, options: { ...options, sub }, logger: commandLogger, t });
     } else if (command.startsWith('plan:') || command === 'plan') {
       const sub = command === 'plan' ? (args[1] || 'show') : command.split(':')[1];
       result = await runImplementationPlan({ args, options: { ...options, sub }, logger: commandLogger, t });
@@ -1355,6 +1381,8 @@ async function main() {
       result = await runMemoryArchive({ args, options, logger: commandLogger, t });
     } else if (command === 'memory:restore' || command === 'memory-restore') {
       result = await runMemoryRestore({ args, options, logger: commandLogger, t });
+    } else if (command === 'memory:trim' || command === 'memory-trim') {
+      result = await runMemoryTrim({ args, options, logger: commandLogger, t });
     } else if (command === 'memory:reflect-prepare' || command === 'memory-reflect-prepare') {
       result = await runMemoryReflectPrepare({ args, options, logger: commandLogger });
     } else if (command === 'memory:reflect-commit' || command === 'memory-reflect-commit') {

package/src/commands/agent-audit.js

@@ -19,8 +19,11 @@
  *
  * Usage:
  *   aioson agent:audit .
- *   aioson agent:audit . --verbose          Show per-section breakdown
- *   aioson agent:audit . --locales          Include locale variant files
+ *   aioson agent:audit . --verbose          Show per-section breakdown
+ *   aioson agent:audit . --locales          Include locale variant files
+ *   aioson agent:audit . --runtime-only     Scan project/runtime surfaces only
+ *   aioson agent:audit . --template-only    Scan template surfaces only
+ *   aioson agent:audit . --inception        Scan project and template surfaces
  *   aioson agent:audit . --fix              Write savings report to .aioson/docs/agent-audit.md
  *   aioson agent:audit . --json
  */
@@ -117,7 +120,7 @@ function parseSections(content) {
 
 // ─── File scanner ─────────────────────────────────────────────────────────────
 
-async function scanAgentFile(filePath, relativePath) {
+async function scanAgentFile(filePath, relativePath, category = 'workspace_agent') {
   let content;
   try {
     content = await fs.readFile(filePath, 'utf8');
@@ -140,10 +143,11 @@ async function scanAgentFile(filePath, relativePath) {
         ? 'over_target'
         : 'ok';
 
-  return {
-    file: relativePath,
-    slug,
-    agent_type: typeDef.type,
+  return {
+    file: relativePath,
+    slug,
+    category,
+    agent_type: typeDef.type,
     chars,
     tokens: estimateTokens(chars),
     target_chars: typeDef.target,
@@ -156,7 +160,7 @@ async function scanAgentFile(filePath, relativePath) {
   };
 }
 
-async function scanDir(dirPath, projectDir, results) {
+async function scanDir(dirPath, projectDir, results, category = 'workspace_agent') {
   let entries;
   try {
     entries = await fs.readdir(dirPath, { withFileTypes: true });
@@ -166,12 +170,70 @@ async function scanDir(dirPath, projectDir, results) {
 
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
-    const filePath = path.join(dirPath, entry.name);
-    const rel = path.relative(projectDir, filePath).split(path.sep).join('/');
-    const result = await scanAgentFile(filePath, rel);
-    if (result) results.push(result);
-  }
-}
+    const filePath = path.join(dirPath, entry.name);
+    const rel = path.relative(projectDir, filePath).split(path.sep).join('/');
+    const result = await scanAgentFile(filePath, rel, category);
+    if (result) results.push(result);
+  }
+}
+
+function normalizeRel(projectDir, filePath) {
+  return path.relative(projectDir, filePath).split(path.sep).join('/');
+}
+
+function getAuditMode(options) {
+  const selected = [
+    options['runtime-only'] ? 'runtime' : null,
+    options['template-only'] ? 'template' : null,
+    options.inception ? 'inception' : null
+  ].filter(Boolean);
+
+  if (selected.length > 1) {
+    return { error: 'conflicting_modes', selected };
+  }
+
+  return { mode: selected[0] || 'inception' };
+}
+
+function buildAgentRoots(targetDir, mode) {
+  const roots = [];
+
+  if (mode === 'runtime' || mode === 'inception') {
+    roots.push({
+      type: 'dir',
+      path: path.join(targetDir, '.aioson', 'agents'),
+      rel: '.aioson/agents',
+      category: 'workspace_agent'
+    });
+    for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+      roots.push({
+        type: 'file',
+        path: path.join(targetDir, name),
+        rel: name,
+        category: 'auto_loaded'
+      });
+    }
+  }
+
+  if (mode === 'template' || mode === 'inception') {
+    roots.push({
+      type: 'dir',
+      path: path.join(targetDir, 'template', '.aioson', 'agents'),
+      rel: 'template/.aioson/agents',
+      category: 'template_agent'
+    });
+    for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+      roots.push({
+        type: 'file',
+        path: path.join(targetDir, 'template', name),
+        rel: `template/${name}`,
+        category: 'auto_loaded'
+      });
+    }
+  }
+
+  return roots;
+}
 
 // ─── Report writer ────────────────────────────────────────────────────────────
 
@@ -238,104 +300,98 @@ function buildMarkdownReport(files, projectDir) {
 
 // ─── Main command ─────────────────────────────────────────────────────────────
 
-async function runAgentAudit({ args, options = {}, logger }) {
-  const targetDir = path.resolve(process.cwd(), args[0] || '.');
-  const verbose = Boolean(options.verbose || options.v);
-  const includeLocales = Boolean(options.locales);
-  const writeFix = Boolean(options.fix);
-
-  const agentsDir = path.join(targetDir, 'template', '.aioson', 'agents');
-  const rootAgentsDir = path.join(targetDir, '.aioson', 'agents');
-
-  const files = [];
-
-  // Scan template agents (this project)
-  if (await dirExists(agentsDir)) {
-    await scanDir(agentsDir, targetDir, files);
-  }
-  // Scan project agents (when used inside a project)
-  if (await dirExists(rootAgentsDir)) {
-    await scanDir(rootAgentsDir, targetDir, files);
-  }
-  // Scan auto-loaded files
-  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
-    for (const base of [path.join(targetDir, 'template'), targetDir]) {
-      const fp = path.join(base, name);
-      const rel = path.relative(targetDir, fp).split(path.sep).join('/');
-      const r = await scanAgentFile(fp, rel);
-      if (r) files.push(r);
-    }
-  }
-
-  // Optionally include locales
-  if (includeLocales) {
-    const localesBase = path.join(targetDir, 'template', '.aioson', 'locales');
-    try {
-      const langs = await fs.readdir(localesBase, { withFileTypes: true });
-      for (const lang of langs) {
-        if (!lang.isDirectory()) continue;
-        await scanDir(
-          path.join(localesBase, lang.name, 'agents'),
-          targetDir,
-          files
-        );
-      }
-    } catch { /* locales dir optional */ }
-  }
-
-  if (files.length === 0) {
-    if (!options.json) logger.log('No agent files found. Run from the aioson project root or a project with .aioson/agents/.');
-    return { ok: false, reason: 'no_files' };
-  }
-
-  // Sort by size descending
-  files.sort((a, b) => b.chars - a.chars);
-
-  if (options.json) return { ok: true, files };
-
-  // ── Console report ─────────────────────────────────────────────────────────
-  const overHard = files.filter((f) => f.status === 'over_hard');
-  const overTarget = files.filter((f) => f.status === 'over_target');
-  const totalTokens = files.reduce((s, f) => s + f.tokens, 0);
-  const totalSavings = files.reduce((s, f) => s + f.savings_tokens, 0);
-
-  logger.log('Agent Audit');
-  logger.log('─'.repeat(70));
-  logger.log(`Files scanned  : ${files.length}`);
-  logger.log(`Total tokens   : ~${totalTokens.toLocaleString()} per session`);
-  logger.log(`Over hard limit: ${overHard.length}   Over target: ${overTarget.length}`);
-  logger.log(`Potential save : ~${totalSavings.toLocaleString()} tokens/session (on-demand split)`);
-  logger.log('');
-
-  // File table
-  const COL = { file: 45, type: 14, size: 9, tokens: 12, status: 8 };
-  logger.log(
-    'File'.padEnd(COL.file) +
-    'Type'.padEnd(COL.type) +
-    'Size'.padEnd(COL.size) +
-    'Tokens'.padEnd(COL.tokens) +
-    'Status'
-  );
-  logger.log('─'.repeat(70));
-
-  for (const f of files) {
-    const statusLabel = { ok: '✓ ok', over_target: '⚠ target', over_hard: '✗ hard' }[f.status];
-    logger.log(
-      f.file.slice(0, COL.file - 1).padEnd(COL.file) +
-      f.agent_type.padEnd(COL.type) +
-      formatKb(f.chars).padEnd(COL.size) +
-      formatTokens(f.chars).padEnd(COL.tokens) +
-      statusLabel
-    );
-
-    if (verbose && f.sections.length > 0) {
-      const topSections = [...f.sections].sort((a, b) => b.chars - a.chars).slice(0, 5);
-      for (const s of topSections) {
-        const flag = s.onDemandCandidate ? ' [on-demand candidate]' : '';
-        logger.log(`  ${'§ ' + s.title.slice(0, 40)}  ${formatKb(s.chars)}${flag}`);
-      }
-    }
-  }
+async function runAgentAudit({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const verbose = Boolean(options.verbose || options.v);
+  const includeLocales = Boolean(options.locales);
+  const writeFix = Boolean(options.fix);
+  const modeResult = getAuditMode(options);
+
+  if (modeResult.error) {
+    if (!options.json) logger.error('Choose only one audit mode: --runtime-only, --template-only, or --inception.');
+    return { ok: false, reason: modeResult.error, selected: modeResult.selected };
+  }
+
+  const mode = modeResult.mode;
+  const scanRoots = buildAgentRoots(targetDir, mode);
+
+  const files = [];
+
+  for (const root of scanRoots) {
+    if (root.type === 'dir') {
+      if (await dirExists(root.path)) await scanDir(root.path, targetDir, files, root.category);
+      continue;
+    }
+
+    const r = await scanAgentFile(root.path, normalizeRel(targetDir, root.path), root.category);
+    if (r) files.push(r);
+  }
+
+  // Optionally include locales
+  if (includeLocales && (mode === 'runtime' || mode === 'inception')) {
+    await scanLocaleAgents(path.join(targetDir, '.aioson', 'locales'), targetDir, files, 'workspace_agent');
+  }
+  if (includeLocales && (mode === 'template' || mode === 'inception')) {
+    await scanLocaleAgents(path.join(targetDir, 'template', '.aioson', 'locales'), targetDir, files, 'template_agent');
+  }
+
+  const roots = scanRoots.map((r) => r.rel);
+
+  if (files.length === 0) {
+    if (!options.json) logger.log('No agent files found. Run from the aioson project root or a project with .aioson/agents/.');
+    return { ok: false, reason: 'no_files', mode, roots };
+  }
+
+  // Sort by size descending
+  files.sort((a, b) => b.chars - a.chars);
+
+  if (options.json) return { ok: true, mode, roots, files };
+
+  // ── Console report ─────────────────────────────────────────────────────────
+  const overHard = files.filter((f) => f.status === 'over_hard');
+  const overTarget = files.filter((f) => f.status === 'over_target');
+  const totalTokens = files.reduce((s, f) => s + f.tokens, 0);
+  const totalSavings = files.reduce((s, f) => s + f.savings_tokens, 0);
+
+  logger.log('Agent Audit');
+  logger.log('─'.repeat(70));
+  logger.log(`Mode           : ${mode}`);
+  logger.log(`Roots          : ${roots.join(', ')}`);
+  logger.log(`Files scanned  : ${files.length}`);
+  logger.log(`Total tokens   : ~${totalTokens.toLocaleString()} per session`);
+  logger.log(`Over hard limit: ${overHard.length}   Over target: ${overTarget.length}`);
+  logger.log(`Potential save : ~${totalSavings.toLocaleString()} tokens/session (on-demand split)`);
+  logger.log('');
+
+  // File table
+  const COL = { file: 45, type: 14, size: 9, tokens: 12, status: 8 };
+  logger.log(
+    'File'.padEnd(COL.file) +
+    'Type'.padEnd(COL.type) +
+    'Size'.padEnd(COL.size) +
+    'Tokens'.padEnd(COL.tokens) +
+    'Status'
+  );
+  logger.log('─'.repeat(70));
+
+  for (const f of files) {
+    const statusLabel = { ok: '✓ ok', over_target: '⚠ target', over_hard: '✗ hard' }[f.status];
+    logger.log(
+      f.file.slice(0, COL.file - 1).padEnd(COL.file) +
+      f.agent_type.padEnd(COL.type) +
+      formatKb(f.chars).padEnd(COL.size) +
+      formatTokens(f.chars).padEnd(COL.tokens) +
+      statusLabel
+    );
+
+    if (verbose && f.sections.length > 0) {
+      const topSections = [...f.sections].sort((a, b) => b.chars - a.chars).slice(0, 5);
+      for (const s of topSections) {
+        const flag = s.onDemandCandidate ? ' [on-demand candidate]' : '';
+        logger.log(`  ${'§ ' + s.title.slice(0, 40)}  ${formatKb(s.chars)}${flag}`);
+      }
+    }
+  }
 
   logger.log('');
 
@@ -375,15 +431,29 @@ async function runAgentAudit({ args, options = {}, logger }) {
     logger.log('     Run with --verbose to see per-section breakdown.');
   }
 
-  return {
-    ok: true,
-    files: files.length,
-    over_hard: overHard.length,
-    over_target: overTarget.length,
-    total_tokens: totalTokens,
+  return {
+    ok: true,
+    mode,
+    roots,
+    files: files.length,
+    over_hard: overHard.length,
+    over_target: overTarget.length,
+    total_tokens: totalTokens,
     potential_savings_tokens: totalSavings
   };
-}
+}
+
+async function scanLocaleAgents(localesBase, targetDir, files, category) {
+  try {
+    const langs = await fs.readdir(localesBase, { withFileTypes: true });
+    for (const lang of langs) {
+      if (!lang.isDirectory()) continue;
+      await scanDir(path.join(localesBase, lang.name, 'agents'), targetDir, files, category);
+    }
+  } catch {
+    // locales dir optional
+  }
+}
 
 async function dirExists(dirPath) {
   try {