@jaimevalasek/aioson 1.21.3 → 1.21.4

package/CHANGELOG.md

@@ -29,7 +29,7 @@ All notable changes to this project will be documented in this file.
 ### 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-06-XX
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.21.3",
+  "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

@@ -58,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');
@@ -80,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 {
@@ -325,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',
@@ -376,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',
@@ -812,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');
@@ -837,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');
@@ -1164,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') {
@@ -1216,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') {
@@ -1268,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 });

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 {

package/src/commands/artifact-validate.js

@@ -70,8 +70,9 @@ async function runArtifactValidate({ args, options = {}, logger }) {
     reqCount = `${new Set(reqs).size} REQs, ${new Set(acs).size} ACs`;
   }
 
-  // Conformance required?
-  const conformanceRequired = classification === 'MEDIUM';
+  // Conformance required?
+  const conformanceRequired = classification === 'MEDIUM';
+  const designDocRequired = classification === 'SMALL' || classification === 'MEDIUM';
 
   // Build chain items
   const chain = [
@@ -110,15 +111,29 @@ async function runArtifactValidate({ args, options = {}, logger }) {
       required: true,
       indent: 1
     },
-    {
-      name: 'architecture.md',
-      exists: artifacts.architecture.exists,
-      detail: null,
-      required: true,
-      indent: 1
-    },
-    {
-      name: `implementation-plan-${slug}.md`,
+    {
+      name: 'architecture.md',
+      exists: artifacts.architecture.exists,
+      detail: null,
+      required: true,
+      indent: 1
+    },
+    {
+      name: 'design-doc.md',
+      exists: artifacts.design_doc.exists,
+      detail: designDocRequired ? 'pre-dev design governance contract' : `SMALL/MEDIUM only — NOT required for ${classification || 'MICRO'}`,
+      required: designDocRequired,
+      indent: 1
+    },
+    {
+      name: 'readiness.md',
+      exists: artifacts.readiness.exists,
+      detail: designDocRequired ? 'pre-dev readiness contract' : `SMALL/MEDIUM only — NOT required for ${classification || 'MICRO'}`,
+      required: designDocRequired,
+      indent: 1
+    },
+    {
+      name: `implementation-plan-${slug}.md`,
       exists: artifacts.implementation_plan.exists,
       detail: planStatus ? `status: ${planStatus}` : null,
       required: true,
@@ -143,9 +158,11 @@ async function runArtifactValidate({ args, options = {}, logger }) {
   const ARTIFACT_OWNER_MAP = {
     'project.context.md': { agent: '@setup', reason: 'setup not complete' },
     [`prd-${slug}.md`]: { agent: '@product', reason: 'PRD not produced yet' },
-    [`requirements-${slug}.md`]: { agent: '@analyst', reason: 'requirements not produced yet (Gate A)' },
-    'architecture.md': { agent: '@architect', reason: 'architecture not produced yet (Gate B)' },
-    [`implementation-plan-${slug}.md`]: { agent: '@pm', reason: 'implementation plan not produced yet (Gate C)' },
+    [`requirements-${slug}.md`]: { agent: '@analyst', reason: 'requirements not produced yet (Gate A)' },
+    'architecture.md': { agent: '@architect', reason: 'architecture not produced yet (Gate B)' },
+    'design-doc.md': { agent: '@discovery-design-doc', reason: 'design governance contract not produced yet' },
+    'readiness.md': { agent: '@discovery-design-doc', reason: 'readiness contract not produced yet' },
+    [`implementation-plan-${slug}.md`]: { agent: '@pm', reason: 'implementation plan not produced yet (Gate C)' },
     [`spec-${slug}.md`]: { agent: '@analyst', reason: 'spec not produced yet — @analyst seeds the feature memory' },
     [`conformance-${slug}.yaml`]: { agent: '@analyst', reason: 'conformance contract missing — @analyst creates it for MEDIUM features' }
   };