@jaimevalasek/aioson 1.7.2 → 1.8.0

package/src/commands/workspace.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { exists } = require('../utils');
+const { readConfig } = require('./config');
+
+const WORKSPACE_FILE = '.aioson/workspace.json';
+const DEFAULT_BASE_URL = 'https://aioson.com';
+
+function slugify(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+}
+
+async function findProjectRoot(startDir) {
+  let current = path.resolve(startDir || '.');
+  for (let i = 0; i < 12; i++) {
+    try {
+      await fs.access(path.join(current, '.aioson'));
+      return current;
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+  return path.resolve(startDir || '.');
+}
+
+async function readWorkspace(projectDir) {
+  const wsPath = path.join(projectDir, WORKSPACE_FILE);
+  if (!(await exists(wsPath))) return null;
+  try {
+    return JSON.parse(await fs.readFile(wsPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function writeWorkspace(projectDir, data) {
+  const wsPath = path.join(projectDir, WORKSPACE_FILE);
+  await fs.writeFile(wsPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+  return wsPath;
+}
+
+async function runWorkspaceInit({ args, options, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const projectDir = await findProjectRoot(targetDir);
+  const wsPath = path.join(projectDir, WORKSPACE_FILE);
+
+  if ((await exists(wsPath)) && !options.force) {
+    const ws = JSON.parse(await fs.readFile(wsPath, 'utf8'));
+    const config = await readConfig();
+    const baseUrl = String(config.aiosonBaseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+    logger.log(t('workspace.already_linked', { slug: ws.slug, url: `${baseUrl}/workspaces/${ws.slug}` }));
+    return { ok: true, slug: ws.slug, alreadyExists: true };
+  }
+
+  const config = await readConfig();
+  const baseUrl = String(config.aiosonBaseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+  const username = slugify(config.aiosonUsername || 'local');
+  const projectName = slugify(options.name || path.basename(projectDir));
+  const baseSlug = `${username}-${projectName}`;
+  const token = config.aiosonToken;
+
+  let workspaceId = `wks_local_${Date.now()}`;
+  let finalSlug = baseSlug;
+
+  if (token) {
+    try {
+      logger.log(t('workspace.registering'));
+      const response = await fetch(`${baseUrl}/api/workspaces`, {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${token}`,
+          'content-type': 'application/json',
+          accept: 'application/json'
+        },
+        body: JSON.stringify({ slug: baseSlug, projectName }),
+        signal: AbortSignal.timeout(10000)
+      });
+      if (response.ok) {
+        const data = await response.json();
+        // /api/workspaces POST returns { ok, workspace: { id, name, slug } }
+        workspaceId = data.workspace?.id || data.workspaceId || workspaceId;
+        finalSlug = data.workspace?.slug || data.slug || baseSlug;
+      }
+    } catch {
+      // Offline — use local ID, will sync later
+    }
+  }
+
+  const wsData = { slug: finalSlug, workspaceId, createdAt: new Date().toISOString() };
+  const writtenPath = await writeWorkspace(projectDir, wsData);
+
+  logger.log(t('workspace.init_ok', { slug: finalSlug, path: writtenPath, url: `${baseUrl}/workspaces/${finalSlug}` }));
+  return { ok: true, slug: finalSlug, workspaceId, path: writtenPath };
+}
+
+async function runWorkspaceStatus({ args, options, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const projectDir = await findProjectRoot(targetDir);
+  const ws = await readWorkspace(projectDir);
+
+  if (!ws) {
+    logger.log(t('workspace.not_linked'));
+    logger.log(t('workspace.init_hint'));
+    return { ok: true, linked: false };
+  }
+
+  const config = await readConfig();
+  const baseUrl = String(config.aiosonBaseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+
+  logger.log(t('workspace.status_slug', { slug: ws.slug }));
+  logger.log(t('workspace.status_id', { id: ws.workspaceId }));
+  logger.log(t('workspace.status_url', { url: `${baseUrl}/workspaces/${ws.slug}` }));
+  logger.log(t('workspace.status_created', { date: ws.createdAt }));
+
+  return { ok: true, linked: true, ...ws };
+}
+
+async function runWorkspaceOpen({ args, options, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const projectDir = await findProjectRoot(targetDir);
+  const ws = await readWorkspace(projectDir);
+
+  if (!ws) {
+    logger.log(t('workspace.not_linked'));
+    logger.log(t('workspace.init_hint'));
+    return { ok: false, error: { code: 'not_linked' } };
+  }
+
+  const config = await readConfig();
+  const baseUrl = String(config.aiosonBaseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+  const url = `${baseUrl}/workspaces/${ws.slug}`;
+  logger.log(t('workspace.open_url', { url }));
+  return { ok: true, url };
+}
+
+module.exports = { runWorkspaceInit, runWorkspaceStatus, runWorkspaceOpen, readWorkspace, findProjectRoot };

package/src/constants.js

@@ -29,7 +29,9 @@ const MANAGED_FILES = [
   '.aioson/agents/pm.md',
   '.aioson/agents/dev.md',
   '.aioson/agents/qa.md',
+  '.aioson/agents/tester.md',
   '.aioson/agents/orchestrator.md',
+  '.aioson/agents/pentester.md',
   '.aioson/agents/squad.md',
   '.aioson/agents/orache.md',
   '.aioson/agents/genome.md',
@@ -39,78 +41,28 @@ const MANAGED_FILES = [
   '.aioson/agents/profiler-enricher.md',
   '.aioson/agents/profiler-forge.md',
   '.aioson/agents/copywriter.md',
-  '.aioson/locales/en/agents/setup.md',
-  '.aioson/locales/en/agents/discovery-design-doc.md',
-  '.aioson/locales/en/agents/analyst.md',
-  '.aioson/locales/en/agents/architect.md',
-  '.aioson/locales/en/agents/ux-ui.md',
-  '.aioson/locales/en/agents/product.md',
-  '.aioson/locales/en/agents/deyvin.md',
-  '.aioson/locales/en/agents/pair.md',
-  '.aioson/locales/en/agents/pm.md',
-  '.aioson/locales/en/agents/dev.md',
-  '.aioson/locales/en/agents/qa.md',
-  '.aioson/locales/en/agents/orchestrator.md',
-  '.aioson/locales/en/agents/squad.md',
-  '.aioson/locales/en/agents/orache.md',
-  '.aioson/locales/en/agents/genome.md',
-  '.aioson/locales/en/agents/profiler-researcher.md',
-  '.aioson/locales/en/agents/profiler-enricher.md',
-  '.aioson/locales/en/agents/profiler-forge.md',
-  '.aioson/locales/pt-BR/agents/setup.md',
-  '.aioson/locales/pt-BR/agents/discovery-design-doc.md',
-  '.aioson/locales/pt-BR/agents/analyst.md',
-  '.aioson/locales/pt-BR/agents/architect.md',
-  '.aioson/locales/pt-BR/agents/ux-ui.md',
-  '.aioson/locales/pt-BR/agents/product.md',
-  '.aioson/locales/pt-BR/agents/deyvin.md',
-  '.aioson/locales/pt-BR/agents/pair.md',
-  '.aioson/locales/pt-BR/agents/pm.md',
-  '.aioson/locales/pt-BR/agents/dev.md',
-  '.aioson/locales/pt-BR/agents/qa.md',
-  '.aioson/locales/pt-BR/agents/orchestrator.md',
-  '.aioson/locales/pt-BR/agents/squad.md',
-  '.aioson/locales/pt-BR/agents/orache.md',
-  '.aioson/locales/pt-BR/agents/genome.md',
-  '.aioson/locales/pt-BR/agents/profiler-researcher.md',
-  '.aioson/locales/pt-BR/agents/profiler-enricher.md',
-  '.aioson/locales/pt-BR/agents/profiler-forge.md',
-  '.aioson/locales/es/agents/setup.md',
-  '.aioson/locales/es/agents/discovery-design-doc.md',
-  '.aioson/locales/es/agents/analyst.md',
-  '.aioson/locales/es/agents/architect.md',
-  '.aioson/locales/es/agents/ux-ui.md',
-  '.aioson/locales/es/agents/product.md',
-  '.aioson/locales/es/agents/deyvin.md',
-  '.aioson/locales/es/agents/pair.md',
-  '.aioson/locales/es/agents/pm.md',
-  '.aioson/locales/es/agents/dev.md',
-  '.aioson/locales/es/agents/qa.md',
-  '.aioson/locales/es/agents/orchestrator.md',
-  '.aioson/locales/es/agents/squad.md',
-  '.aioson/locales/es/agents/orache.md',
-  '.aioson/locales/es/agents/genome.md',
-  '.aioson/locales/es/agents/profiler-researcher.md',
-  '.aioson/locales/es/agents/profiler-enricher.md',
-  '.aioson/locales/es/agents/profiler-forge.md',
-  '.aioson/locales/fr/agents/setup.md',
-  '.aioson/locales/fr/agents/discovery-design-doc.md',
-  '.aioson/locales/fr/agents/analyst.md',
-  '.aioson/locales/fr/agents/architect.md',
-  '.aioson/locales/fr/agents/ux-ui.md',
-  '.aioson/locales/fr/agents/product.md',
-  '.aioson/locales/fr/agents/deyvin.md',
-  '.aioson/locales/fr/agents/pair.md',
-  '.aioson/locales/fr/agents/pm.md',
-  '.aioson/locales/fr/agents/dev.md',
-  '.aioson/locales/fr/agents/qa.md',
-  '.aioson/locales/fr/agents/orchestrator.md',
-  '.aioson/locales/fr/agents/squad.md',
-  '.aioson/locales/fr/agents/orache.md',
-  '.aioson/locales/fr/agents/genome.md',
-  '.aioson/locales/fr/agents/profiler-researcher.md',
-  '.aioson/locales/fr/agents/profiler-enricher.md',
-  '.aioson/locales/fr/agents/profiler-forge.md',
+  '.aioson/docs/squad/package-contract.md',
+  '.aioson/docs/squad/creation-flow.md',
+  '.aioson/docs/squad/research-loop.md',
+  '.aioson/docs/squad/quality-lens.md',
+  '.aioson/docs/squad/workflow-quality.md',
+  '.aioson/docs/squad/content-output.md',
+  '.aioson/docs/squad/session-operations.md',
+  '.aioson/docs/squad/genome-bindings.md',
+  '.aioson/docs/product/conversation-playbook.md',
+  '.aioson/docs/product/research-loop.md',
+  '.aioson/docs/product/quality-lens.md',
+  '.aioson/docs/product/prd-contract.md',
+  '.aioson/docs/deyvin/continuity-recovery.md',
+  '.aioson/docs/deyvin/pair-execution.md',
+  '.aioson/docs/deyvin/runtime-handoffs.md',
+  '.aioson/docs/deyvin/debugging-escalation.md',
+  '.aioson/docs/sheldon/research-loop.md',
+  '.aioson/docs/sheldon/web-intelligence.md',
+  '.aioson/docs/sheldon/quality-lens.md',
+  '.aioson/docs/sheldon/enrichment-paths.md',
+  '.aioson/docs/dev/stack-conventions.md',
+  '.aioson/docs/dev/execution-discipline.md',
   '.aioson/skills/static/laravel-conventions.md',
   '.aioson/skills/static/tall-stack-patterns.md',
   '.aioson/skills/static/jetstream-setup.md',
@@ -217,7 +169,7 @@ const CONTEXT_REQUIRED_FIELDS = [
 ];
 
 const CONTEXT_ALLOWED_CLASSIFICATIONS = ['MICRO', 'SMALL', 'MEDIUM'];
-const CONTEXT_ALLOWED_PROJECT_TYPES = ['web_app', 'api', 'site', 'script', 'dapp'];
+const CONTEXT_ALLOWED_PROJECT_TYPES = ['web_app', 'api', 'site', 'script', 'dapp', 'desktop_app'];
 const CONTEXT_ALLOWED_PROFILES = ['developer', 'beginner', 'team'];
 
 const AGENT_DEFINITIONS = [
@@ -295,7 +247,8 @@ const AGENT_DEFINITIONS = [
       '.aioson/context/project.context.md',
       '.aioson/context/prd.md or .aioson/context/prd-{slug}.md',
       '.aioson/context/discovery.md',
-      '.aioson/context/architecture.md'
+      '.aioson/context/architecture.md',
+      '.aioson/context/ui-spec.md (when present)'
     ],
     output: '.aioson/context/prd.md or prd-{slug}.md (enriched with delivery plan and acceptance criteria)'
   },
@@ -311,6 +264,17 @@ const AGENT_DEFINITIONS = [
     ],
     output: 'code changes'
   },
+  {
+    id: 'pentester',
+    displayName: 'Pentester',
+    command: '@pentester',
+    path: '.aioson/agents/pentester.md',
+    dependsOn: [
+      '.aioson/context/project.context.md',
+      '.aioson/context/spec-{slug}.md (active feature)'
+    ],
+    output: '.aioson/context/security-findings-{slug}.json'
+  },
   {
     id: 'qa',
     displayName: 'QA',
@@ -333,9 +297,12 @@ const AGENT_DEFINITIONS = [
     command: '@orchestrator',
     path: '.aioson/agents/orchestrator.md',
     dependsOn: [
+      '.aioson/context/project.context.md',
       '.aioson/context/discovery.md',
       '.aioson/context/architecture.md',
-      '.aioson/context/prd.md'
+      '.aioson/context/prd.md or .aioson/context/prd-{slug}.md',
+      '.aioson/context/ui-spec.md (when present)',
+      '.aioson/context/implementation-plan.md or implementation-plan-{slug}.md (when present)'
     ],
     output: '.aioson/context/parallel/*.status.md'
   },

package/src/context-memory.js

@@ -21,6 +21,11 @@ const SCAN_INDEX_FILE = `${CONTEXT_DIR}/scan-index.md`;
 const SCAN_FOLDERS_FILE = `${CONTEXT_DIR}/scan-folders.md`;
 const SCAN_AIOSON_FILE = `${CONTEXT_DIR}/scan-aioson.md`;
 const CONTEXT_PACK_FILE = `${CONTEXT_DIR}/context-pack.md`;
+const BOOTSTRAP_DIR = '.aioson/context/bootstrap';
+const BOOTSTRAP_WHAT_IS = `${BOOTSTRAP_DIR}/what-is.md`;
+const BOOTSTRAP_HOW_IT_WORKS = `${BOOTSTRAP_DIR}/how-it-works.md`;
+const BOOTSTRAP_WHAT_IT_DOES = `${BOOTSTRAP_DIR}/what-it-does.md`;
+const BOOTSTRAP_CURRENT_STATE = `${BOOTSTRAP_DIR}/current-state.md`;
 
 const SPEC_SECTION_ALIASES = {
   stack: ['stack'],
@@ -138,6 +143,34 @@ const CONTEXT_DOC_SPECS = [
     group: 'scan',
     readWhen: 'you need generated context pages, squads, genomes or local MCP artifacts',
     tags: ['scan', 'brownfield', 'aioson']
+  },
+  {
+    relPath: BOOTSTRAP_WHAT_IS,
+    title: 'System Identity',
+    group: 'bootstrap',
+    readWhen: 'you need to understand what the system IS, who uses it, and why it exists',
+    tags: ['bootstrap', 'identity', 'semantic']
+  },
+  {
+    relPath: BOOTSTRAP_HOW_IT_WORKS,
+    title: 'System Mechanics',
+    group: 'bootstrap',
+    readWhen: 'you need to understand how the system works — architecture, modules, data flow',
+    tags: ['bootstrap', 'architecture', 'semantic']
+  },
+  {
+    relPath: BOOTSTRAP_WHAT_IT_DOES,
+    title: 'System Features',
+    group: 'bootstrap',
+    readWhen: 'you need to know what features exist, business rules, and user workflows',
+    tags: ['bootstrap', 'features', 'semantic']
+  },
+  {
+    relPath: BOOTSTRAP_CURRENT_STATE,
+    title: 'System Current State',
+    group: 'bootstrap',
+    readWhen: 'you need to know what is implemented, in progress, or planned',
+    tags: ['bootstrap', 'state', 'semantic']
   }
 ];
 
@@ -499,9 +532,10 @@ function buildMemoryIndexMarkdown({ generatedAt, catalog }) {
     ''
   ];
 
-  const groupOrder = ['foundation', 'system', 'development', 'scope', 'modules', 'scan'];
+  const groupOrder = ['foundation', 'bootstrap', 'system', 'development', 'scope', 'modules', 'scan'];
   const groupTitles = {
     foundation: 'Foundation Docs',
+    bootstrap: 'Bootstrap — Semantic Knowledge Cache',
     system: 'System Memory',
     development: 'Development Memory',
     scope: 'Scope Docs',
@@ -534,6 +568,7 @@ function rankContextDoc(doc, { agent, goal, module }) {
   const lowerGoal = normalizeForLookup(goal);
   const lowerAgent = normalizeForLookup(agent);
   const lowerModule = normalizeForLookup(module);
+  const lookupText = `${lowerAgent} ${lowerGoal}`.trim();
 
   if (doc.relPath === PROJECT_CONTEXT_FILE) {
     score += 100;
@@ -579,6 +614,24 @@ function rankContextDoc(doc, { agent, goal, module }) {
     score += 35;
     reasons.push('readiness signal');
   }
+  if (doc.group === 'bootstrap') {
+    if (doc.relPath === BOOTSTRAP_WHAT_IS && /(product|analyst|what|identity|understand|discover|bootstrap|memory|continuity)/.test(lookupText)) {
+      score += 70;
+      reasons.push('semantic system identity');
+    }
+    if (doc.relPath === BOOTSTRAP_HOW_IT_WORKS && /(dev|architect|how|architecture|implement|refactor|bootstrap|memory|continuity)/.test(lookupText)) {
+      score += 70;
+      reasons.push('semantic system mechanics');
+    }
+    if (doc.relPath === BOOTSTRAP_WHAT_IT_DOES && /(product|analyst|feature|business|rule|workflow|bootstrap|memory|continuity)/.test(lookupText)) {
+      score += 65;
+      reasons.push('semantic features and business rules');
+    }
+    if (doc.relPath === BOOTSTRAP_CURRENT_STATE && /(dev|qa|state|current|progress|status|bootstrap|memory|continuity)/.test(lookupText)) {
+      score += 65;
+      reasons.push('semantic current state');
+    }
+  }
   if (/module-/.test(doc.relPath) && lowerModule) {
     if (normalizeForLookup(doc.relPath).includes(lowerModule)) {
       score += 80;
@@ -737,6 +790,67 @@ async function writeDerivedContextMemory({
   };
 }
 
+async function collectActiveDossiers(targetDir) {
+  const featuresDir = path.join(targetDir, CONTEXT_DIR, 'features');
+  let slugs = [];
+  try {
+    const entries = await fs.readdir(featuresDir, { withFileTypes: true });
+    slugs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+
+  const active = [];
+  for (const slug of slugs) {
+    const p = path.join(featuresDir, slug, 'dossier.md');
+    try {
+      const raw = await fs.readFile(p, 'utf8');
+      const statusMatch = raw.match(/^status:\s*(\S+)\s*$/m);
+      const updatedMatch = raw.match(/^last_updated_at:\s*(\S+)\s*$/m);
+      if (!statusMatch || statusMatch[1] !== 'active') continue;
+      const relPath = `${CONTEXT_DIR}/features/${slug}/dossier.md`;
+      active.push({
+        relPath,
+        slug,
+        lastUpdatedAt: updatedMatch ? updatedMatch[1] : null,
+        title: `Feature Dossier (${slug})`,
+        group: 'dossier',
+        readWhen: `active feature "${slug}" synthesis — why, what, code map, agent trail`,
+        tags: ['dossier', 'feature', 'active'],
+        exists: true
+      });
+    } catch {
+      // skip unreadable
+    }
+  }
+
+  // Sort by last_updated_at descending (most recent first)
+  active.sort((a, b) => {
+    if (!a.lastUpdatedAt && !b.lastUpdatedAt) return 0;
+    if (!a.lastUpdatedAt) return 1;
+    if (!b.lastUpdatedAt) return -1;
+    return b.lastUpdatedAt.localeCompare(a.lastUpdatedAt);
+  });
+
+  return active;
+}
+
+function rankDossier(dossier, { agent, goal }, rank) {
+  // Base score: between PRD (45) and bootstrap (65). Most recent dossier gets 60.
+  let score = 60 - rank * 5;
+  const reasons = [`active feature dossier (${dossier.slug})`];
+  const lookupText = `${normalizeForLookup(agent)} ${normalizeForLookup(goal)}`.trim();
+  if (lookupText.includes(dossier.slug.replace(/-/g, ' '))) {
+    score += 15;
+    reasons.push('matches active feature slug');
+  }
+  if (/(dev|architect|qa|implement|feature|dossier)/.test(lookupText)) {
+    score += 10;
+    reasons.push('agent/goal matches dossier context');
+  }
+  return { score: Math.max(score, 0), reasons };
+}
+
 async function createContextPack({
   targetDir,
   agent = '',
@@ -752,15 +866,25 @@ async function createContextPack({
     : 8;
 
   const catalog = (await collectContextCatalog(targetDir)).filter((doc) => doc.exists);
-  const ranked = catalog
-    .map((doc) => {
+
+  // Inject active dossiers as ranked sources (reference, not inline copy)
+  const activeDossiers = await collectActiveDossiers(targetDir);
+  const dossierDocs = activeDossiers.map((d, i) => {
+    const rank = rankDossier(d, { agent, goal }, i);
+    return { ...d, score: rank.score, reason: rank.reasons.join('; ') };
+  });
+
+  const ranked = [
+    ...catalog.map((doc) => {
       const rank = rankContextDoc(doc, { agent, goal, module });
       return {
         ...doc,
         score: rank.score,
         reason: rank.reasons.join('; ') || doc.readWhen
       };
-    })
+    }),
+    ...dossierDocs
+  ]
     .filter((doc) => doc.score > 0)
     .sort((a, b) => b.score - a.score || a.relPath.localeCompare(b.relPath));
 
@@ -826,6 +950,11 @@ module.exports = {
   SCAN_FOLDERS_FILE,
   SCAN_AIOSON_FILE,
   CONTEXT_PACK_FILE,
+  BOOTSTRAP_DIR,
+  BOOTSTRAP_WHAT_IS,
+  BOOTSTRAP_HOW_IT_WORKS,
+  BOOTSTRAP_WHAT_IT_DOES,
+  BOOTSTRAP_CURRENT_STATE,
   buildModuleMemoryRelativePath,
   buildSpecCurrentMarkdown,
   buildSpecHistoryMarkdown,

package/src/context-writer.js

@@ -60,7 +60,7 @@ function normalizeBoolean(value, fallback = false) {
 }
 
 function renderProjectContext(data) {
-  const language = data.conversationLanguage || 'en';
+  const language = data.interactionLanguage || data.conversationLanguage || 'en';
   const codeCommentLanguage = data.codeCommentLanguage || language;
   const generatedAt = data.generatedAt || new Date().toISOString();
   const designSkill = data.designSkill || '';
@@ -80,6 +80,7 @@ profile: "${data.profile}"
 framework: "${data.framework}"
 framework_installed: ${data.frameworkInstalled ? 'true' : 'false'}
 classification: "${data.classification}"
+interaction_language: "${language}"
 conversation_language: "${language}"
 design_skill: "${designSkill}"
 test_runner: "${testRunner}"

package/src/context.js

@@ -86,6 +86,23 @@ function isValidLanguageTag(value) {
   return /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/.test(tag);
 }
 
+function normalizeLanguageTag(value, fallback = 'en') {
+  const tag = String(value || '').trim().replace(/_/g, '-');
+  if (!tag) return fallback;
+  return isValidLanguageTag(tag) ? tag : fallback;
+}
+
+function getInteractionLanguage(data, fallback = 'en') {
+  if (!data || typeof data !== 'object') return fallback;
+  if (Object.prototype.hasOwnProperty.call(data, 'interaction_language')) {
+    return normalizeLanguageTag(data.interaction_language, fallback);
+  }
+  if (Object.prototype.hasOwnProperty.call(data, 'conversation_language')) {
+    return normalizeLanguageTag(data.conversation_language, fallback);
+  }
+  return fallback;
+}
+
 function validateContextData(data) {
   const issues = [];
 
@@ -148,6 +165,18 @@ function validateContextData(data) {
     });
   }
 
+  if (
+    Object.prototype.hasOwnProperty.call(data, 'interaction_language') &&
+    !isValidLanguageTag(data.interaction_language)
+  ) {
+    issues.push({
+      id: 'context:interaction_language:format',
+      key: 'doctor.context_interaction_language_format',
+      params: {},
+      hintKey: 'doctor.context_interaction_language_format_hint'
+    });
+  }
+
   if (
     Object.prototype.hasOwnProperty.call(data, 'conversation_language') &&
     !isValidLanguageTag(data.conversation_language)
@@ -212,6 +241,7 @@ module.exports = {
   parseYamlFrontmatter,
   validateContextData,
   validateProjectContextFile,
-  isValidLanguageTag
+  isValidLanguageTag,
+  normalizeLanguageTag,
+  getInteractionLanguage
 };
-

package/src/doctor.js

@@ -5,8 +5,8 @@ const path = require('node:path');
 const { REQUIRED_FILES } = require('./constants');
 const { installTemplate, TEMPLATE_DIR } = require('./installer');
 const { exists, copyFileWithDir } = require('./utils');
-const { validateProjectContextFile } = require('./context');
-const { applyAgentLocale, resolveAgentLocale } = require('./locales');
+const { validateProjectContextFile, getInteractionLanguage } = require('./context');
+const { applyAgentLocale } = require('./locales');
 
 function parseMajor(version) {
   const cleaned = String(version || '').replace(/^v/, '');
@@ -34,6 +34,14 @@ const GEMINI_COMMAND_EXPECTATIONS = [
   { file: '.gemini/commands/aios-orchestrator.toml', agent: 'orchestrator' }
 ];
 
+const DESIGN_GOVERNANCE_FILES = [
+  '.aioson/design-docs/code-reuse.md',
+  '.aioson/design-docs/componentization.md',
+  '.aioson/design-docs/file-size.md',
+  '.aioson/design-docs/folder-structure.md',
+  '.aioson/design-docs/naming.md'
+];
+
 const GATEWAY_FILE_BY_CHECK_ID = {
   'gateway:claude:contract': 'CLAUDE.md',
   'gateway:codex:contract': 'AGENTS.md',
@@ -79,6 +87,16 @@ async function runDoctor(targetDir) {
     });
   }
 
+  for (const rel of DESIGN_GOVERNANCE_FILES) {
+    checks.push({
+      id: `design-governance:${rel}`,
+      key: 'doctor.required_file',
+      params: { rel },
+      ok: await exists(path.join(targetDir, rel)),
+      hintKey: 'doctor.context_hint'
+    });
+  }
+
   const gatewayChecks = [
     {
       id: 'gateway:claude:contract',
@@ -130,7 +148,7 @@ async function runDoctor(targetDir) {
       key: 'doctor.gateway_gemini_command_pointer',
       params: { file: expectation.file },
       ok: await fileContainsAll(commandPath, [
-        `instruction_file = ".aioson/agents/${expectation.agent}.md"`
+        `@{ .aioson/agents/${expectation.agent}.md }`
       ]),
       hintKey: 'doctor.gateway_gemini_command_pointer_hint',
       hintParams: {
@@ -250,14 +268,36 @@ async function applyDoctorFixes(targetDir, report, options = {}) {
     });
   }
 
+  const missingDesignGovernanceFiles = report.checks
+    .filter((check) => !check.ok && check.id.startsWith('design-governance:'))
+    .map((check) => check.params.rel);
+
+  if (missingDesignGovernanceFiles.length > 0) {
+    const restored = await restoreTemplateFiles(targetDir, missingDesignGovernanceFiles, { dryRun });
+    if (restored.length > 0) changedCount += restored.length;
+    actions.push({
+      id: 'design_governance',
+      applied: restored.length > 0,
+      count: restored.length,
+      missingCount: missingDesignGovernanceFiles.length
+    });
+  } else {
+    actions.push({
+      id: 'design_governance',
+      applied: false,
+      skipped: true,
+      count: 0,
+      missingCount: 0
+    });
+  }
+
   if (
     report.contextValidation &&
     report.contextValidation.parsed &&
     report.contextValidation.valid &&
-    report.contextValidation.data &&
-    report.contextValidation.data.conversation_language
+    report.contextValidation.data
   ) {
-    const locale = resolveAgentLocale(report.contextValidation.data.conversation_language);
+    const locale = getInteractionLanguage(report.contextValidation.data, 'en');
     const localeResult = await applyAgentLocale(targetDir, locale, { dryRun });
     if (localeResult.copied.length > 0) changedCount += localeResult.copied.length;
     actions.push({