@jaimevalasek/aioson 1.7.0 → 1.8.0

package/src/commands/squad-agent-create.js

@@ -9,6 +9,7 @@ const SQUADS_DIR = '.aioson/squads';
 
 const VALID_TYPES = ['agent', 'assistant', 'clone', 'worker'];
 const VALID_TIERS = ['0', '1', '2', '3'];
+const VALID_MODEL_TIERS = ['powerful', 'balanced', 'fast', 'none'];
 const VALID_DISC = [
   'dominant-driver', 'influential-expressive', 'steady-amiable',
   'compliant-analytical', 'dominant-influential', 'influential-steady',
@@ -26,6 +27,11 @@ function slugify(name) {
     .replace(/^-|-$/g, '');
 }
 
+function resolveExecutorModelTier(type, modelTier) {
+  if (type === 'worker') return 'none';
+  return modelTier || 'balanced';
+}
+
 // ---------------------------------------------------------------------------
 // Agent template builder — inspired by AIOX create-agent v3.0 but adapted
 // for aioson's markdown-agent ecosystem (Claude Code, Codex, Gemini CLI).
@@ -49,8 +55,10 @@ function buildAgentTemplate(slug, opts) {
     type = 'agent',
     tier = null,
     disc = null,
+    modelTier = null,
     domain = null,
     specialist = null,
+    localeScope = 'universal',
     withInfra = false
   } = opts;
 
@@ -61,8 +69,8 @@ function buildAgentTemplate(slug, opts) {
   lines.push('');
 
   const identity = scope === 'squad' && squadSlug
-    ? `<!-- identity: squad:${squadSlug}/${slug} | type: ${type}${tier ? ` | tier: ${tier}` : ''} -->`
-    : `<!-- identity: my-agent:${slug} | type: ${type}${tier ? ` | tier: ${tier}` : ''} -->`;
+    ? `<!-- identity: squad:${squadSlug}/${slug} | type: ${type}${tier ? ` | tier: ${tier}` : ''}${modelTier ? ` | modelTier: ${modelTier}` : ''} -->`
+    : `<!-- identity: my-agent:${slug} | type: ${type}${tier ? ` | tier: ${tier}` : ''}${modelTier ? ` | modelTier: ${modelTier}` : ''} -->`;
   lines.push(identity);
   lines.push('');
   lines.push(`> ⚡ **ACTIVATED** — Execute immediately as @${slug}.`);
@@ -88,6 +96,7 @@ function buildAgentTemplate(slug, opts) {
   if (scope === 'squad' && squadSlug) {
     lines.push('## Quick context');
     lines.push(`Squad: ${squadName || squadSlug} | Agent: @${slug} | Type: ${type}${tier ? ` | Tier: ${tier}` : ''}`);
+    lines.push(`Locale scope: ${localeScope}`);
     if (domain) lines.push(`Domain: ${domain}`);
     lines.push('');
   }
@@ -215,7 +224,11 @@ function buildAgentTemplate(slug, opts) {
 
   // ── Hard constraints ────────────────────────────────────────────────────
   lines.push('## Hard constraints');
-  lines.push('- Use `conversation_language` from project context for all interaction');
+  if (scope === 'squad' && localeScope && localeScope !== 'universal') {
+    lines.push(`- This squad is locale-specific (${localeScope}). Use that locale for prompt examples and user-facing output inside this squad.`);
+  } else {
+    lines.push('- Use `interaction_language` from project context for all interaction. If it is absent, fall back to `conversation_language`.');
+  }
   lines.push('- Do not invent facts or requirements — ask when uncertain');
   if (scope === 'squad' && squadSlug) {
     lines.push(`- Stay within squad scope: ${squadSlug}`);
@@ -463,6 +476,8 @@ async function runSquadAgentCreate({ args = [], options = {}, logger = console,
   const type = options.type || 'agent';
   const tier = options.tier || null;
   const disc = options.disc || null;
+  const modelTier = options['model-tier'] || options.modelTier || null;
+  const behavioralProfile = options['behavioral-profile'] || options.behavioralProfile || disc || null;
   const domain = options.domain || null;
   const specialist = options.specialist || null;
   const withInfra = !!options['with-infra'];
@@ -498,6 +513,18 @@ async function runSquadAgentCreate({ args = [], options = {}, logger = console,
     return { ok: false, error: 'invalid_disc' };
   }
 
+  if (behavioralProfile && !VALID_DISC.includes(behavioralProfile)) {
+    const msg = `Invalid behavioral profile: "${behavioralProfile}". Valid: ${VALID_DISC.join(', ')}`;
+    logger.error(msg);
+    return { ok: false, error: 'invalid_behavioral_profile' };
+  }
+
+  if (modelTier && !VALID_MODEL_TIERS.includes(modelTier)) {
+    const msg = `Invalid model tier: "${modelTier}". Use: ${VALID_MODEL_TIERS.join(', ')}`;
+    logger.error(msg);
+    return { ok: false, error: 'invalid_model_tier' };
+  }
+
   // Determine scope
   let resolvedScope = scope;
   if (!resolvedScope) {
@@ -512,6 +539,8 @@ async function runSquadAgentCreate({ args = [], options = {}, logger = console,
 
   // If scope=squad, validate squad exists
   let squadName = null;
+  let squadManifest = null;
+  let localeScope = 'universal';
   if (resolvedScope === 'squad') {
     if (!squadSlug) {
       const squads = await listSquads(projectDir);
@@ -536,8 +565,9 @@ async function runSquadAgentCreate({ args = [], options = {}, logger = console,
     if (await exists(manifestPath)) {
       try {
         const raw = await fs.readFile(manifestPath, 'utf8');
-        const manifest = JSON.parse(raw);
-        squadName = manifest.name || squadSlug;
+        squadManifest = JSON.parse(raw);
+        squadName = squadManifest.name || squadSlug;
+        localeScope = squadManifest.locale_scope || 'universal';
       } catch { squadName = squadSlug; }
     } else {
       squadName = squadSlug;
@@ -565,7 +595,8 @@ async function runSquadAgentCreate({ args = [], options = {}, logger = console,
   // Build agent template
   const content = buildAgentTemplate(slug, {
     mission, focus, scope: resolvedScope,
-    squadSlug, squadName, type, tier, disc, domain, specialist,
+    squadSlug, squadName, type, tier, disc, modelTier: resolveExecutorModelTier(type, modelTier), domain, specialist,
+    localeScope,
     withInfra
   });
 
@@ -574,6 +605,7 @@ async function runSquadAgentCreate({ args = [], options = {}, logger = console,
     logger.log(`[dry-run] Would create: ${agentRelPath}`);
     logger.log(`[dry-run] Scope: ${resolvedScope} | Type: ${type}${tier ? ` | Tier: ${tier}` : ''}`);
     if (resolvedScope === 'squad') logger.log(`[dry-run] Squad: ${squadSlug}`);
+    if (resolvedScope === 'squad') logger.log(`[dry-run] Locale scope: ${localeScope}`);
     if (withInfra) logger.log('[dry-run] Would generate operational infrastructure stubs');
     logger.log('');
     logger.log(content);
@@ -623,17 +655,23 @@ async function runSquadAgentCreate({ args = [], options = {}, logger = console,
     const manifestPath = path.join(projectDir, SQUADS_DIR, squadSlug, 'squad.manifest.json');
     if (await exists(manifestPath)) {
       try {
-        const raw = await fs.readFile(manifestPath, 'utf8');
-        const manifest = JSON.parse(raw);
+        const manifest = squadManifest || JSON.parse(await fs.readFile(manifestPath, 'utf8'));
         if (!Array.isArray(manifest.executors)) manifest.executors = [];
 
         const alreadyExists = manifest.executors.some(e => e.slug === slug);
         if (!alreadyExists) {
+          const resolvedModelTier = resolveExecutorModelTier(type, modelTier);
           manifest.executors.push({
             slug,
+            title: name,
             type,
-            role: slug,
+            role: mission || slug,
             file: agentRelPath,
+            usesLLM: type !== 'worker',
+            deterministic: type === 'worker',
+            modelTier: resolvedModelTier,
+            behavioralProfile: behavioralProfile || undefined,
+            domain: domain || undefined,
             tier: tier ? Number(tier) : undefined,
             disc: disc || undefined,
             skills: [],
@@ -651,6 +689,8 @@ async function runSquadAgentCreate({ args = [], options = {}, logger = console,
   logger.log(`  Agent created: ${agentRelPath}`);
   logger.log(`  Scope: ${resolvedScope === 'my-agents' ? 'my-agents (versioned, available globally)' : `squad:${squadSlug}`}`);
   logger.log(`  Type: ${type}${tier ? ` | Tier: ${tier}` : ''}${disc ? ` | DISC: ${disc}` : ''}`);
+  if (resolvedScope === 'squad') logger.log(`  Locale scope: ${localeScope}`);
+  if (modelTier || type === 'worker') logger.log(`  Model tier: ${resolveExecutorModelTier(type, modelTier)}`);
   logger.log(`  Slug: @${slug}`);
   if (registeredClaude) logger.log('  Registered in CLAUDE.md');
   if (registeredAgents) logger.log('  Registered in AGENTS.md');
@@ -687,6 +727,8 @@ async function runSquadAgentCreate({ args = [], options = {}, logger = console,
     type,
     tier: tier ? Number(tier) : null,
     disc,
+    modelTier: resolveExecutorModelTier(type, modelTier),
+    behavioralProfile,
     squad: squadSlug,
     registeredClaude,
     registeredAgents,

package/src/commands/squad-investigate.js

@@ -22,6 +22,46 @@ async function pathExists(targetPath) {
   }
 }
 
+async function readJsonIfExists(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function writeJson(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+async function syncInvestigationLinkToSquad(projectDir, squadSlug, row) {
+  const manifestPath = path.join(projectDir, '.aioson', 'squads', squadSlug, 'squad.manifest.json');
+  const blueprintPath = path.join(projectDir, '.aioson', 'squads', '.designs', `${squadSlug}.blueprint.json`);
+  const investigationRef = {
+    slug: row.investigation_slug,
+    path: row.report_path || null,
+    confidence: Number(row.confidence) || 0,
+    dimensionsCovered: Number(row.dimensions_covered) || 0,
+    date: row.created_at ? String(row.created_at).slice(0, 10) : null
+  };
+
+  const manifest = await readJsonIfExists(manifestPath);
+  if (!manifest || typeof manifest !== 'object') {
+    throw new Error(`Squad manifest not found: ${manifestPath}`);
+  }
+
+  manifest.investigation = investigationRef;
+  await writeJson(manifestPath, manifest);
+
+  const blueprint = await readJsonIfExists(blueprintPath);
+  if (blueprint && typeof blueprint === 'object') {
+    blueprint.investigation = investigationRef;
+    await writeJson(blueprintPath, blueprint);
+  }
+}
+
 /**
  * Count how many of the 7 investigation dimensions are present in a report.
  * Looks for headers like "## D1:", "## D2:", ..., "## D7:" in the markdown.
@@ -164,8 +204,15 @@ async function handleLink(projectDir, invSlug, squadSlug, { logger, t }) {
   }
   const { db } = handle;
   try {
+    const investigation = getInvestigation(db, invSlug);
+    if (!investigation) {
+      logger.error(t('squad_investigate.not_found', { slug: invSlug }));
+      return { linked: false };
+    }
+
     const success = linkInvestigation(db, invSlug, squadSlug);
     if (success) {
+      await syncInvestigationLinkToSquad(projectDir, squadSlug, investigation);
       logger.log(t('squad_investigate.linked', { investigation: invSlug, squad: squadSlug }));
     } else {
       logger.error(t('squad_investigate.not_found', { slug: invSlug }));
@@ -206,6 +253,12 @@ async function handleRegister(projectDir, reportPath, options, { logger, t }) {
       reportPath: relPath,
       linkedSquadSlug: options.squad || null
     });
+    if (options.squad) {
+      const row = getInvestigation(db, slug);
+      if (row) {
+        await syncInvestigationLinkToSquad(projectDir, options.squad, row);
+      }
+    }
     logger.log(t('squad_investigate.registered', { slug, path: relPath }));
     return { registered: true, slug };
   } finally {

package/src/commands/squad-plan.js

@@ -26,6 +26,23 @@ async function pathExists(targetPath) {
   }
 }
 
+async function readManifestInvestigationMeta(projectDir, squadSlug) {
+  const manifestPath = path.resolve(projectDir, SQUADS_DIR, squadSlug, 'squad.manifest.json');
+  try {
+    const raw = await fs.readFile(manifestPath, 'utf8');
+    const manifest = JSON.parse(raw);
+    const investigation = manifest && typeof manifest.investigation === 'object'
+      ? manifest.investigation
+      : null;
+    return {
+      slug: investigation?.slug || null,
+      path: investigation?.path || null
+    };
+  } catch {
+    return { slug: null, path: null };
+  }
+}
+
 /**
  * Compute hash of squad manifest for staleness detection.
  */
@@ -203,6 +220,7 @@ async function handleStale(projectDir, squadSlug, { logger, t }) {
   const planDate = new Date(meta.created);
   const manifestFile = path.resolve(projectDir, SQUADS_DIR, squadSlug, 'squad.manifest.json');
   let stale = false;
+  const investigationMeta = await readManifestInvestigationMeta(projectDir, squadSlug);
 
   try {
     const stat = await fs.stat(manifestFile);
@@ -231,6 +249,19 @@ async function handleStale(projectDir, squadSlug, { logger, t }) {
     // designs dir may not exist
   }
 
+  if (investigationMeta.path) {
+    try {
+      const invFile = path.resolve(projectDir, investigationMeta.path);
+      const stat = await fs.stat(invFile);
+      if (stat.mtime > planDate) {
+        logger.log('  ⚠ investigation report modified after plan was created');
+        stale = true;
+      }
+    } catch {
+      // linked investigation may be missing on disk
+    }
+  }
+
   if (stale) {
     logger.log(t('squad_plan.is_stale'));
   } else {
@@ -260,6 +291,7 @@ async function handleRegister(projectDir, squadSlug, { logger, t }) {
   const meta = parsePlanFrontmatter(content);
   const rounds = countRounds(content);
   const hash = await computeManifestHash(projectDir, squadSlug);
+  const investigationMeta = await readManifestInvestigationMeta(projectDir, squadSlug);
 
   const handle = await openRuntimeDb(projectDir);
   const { db } = handle;
@@ -270,7 +302,7 @@ async function handleRegister(projectDir, squadSlug, { logger, t }) {
       roundsTotal: rounds,
       roundsCompleted: 0,
       basedOnBlueprint: meta.based_on_blueprint || null,
-      basedOnInvestigation: meta.based_on_investigation || null,
+      basedOnInvestigation: meta.based_on_investigation || investigationMeta.slug || investigationMeta.path || null,
       sourceHash: hash
     });
     logger.log(t('squad_plan.registered', { planSlug, rounds }));

package/src/commands/squad-scaffold.js

@@ -5,8 +5,9 @@
  *
  * Usage:
  *   aioson squad:scaffold . --slug=content-team --name="Content Team" --mode=content
- *   aioson squad:scaffold . --slug=dev-core --name="Dev Core" --mode=code
- *   aioson squad:scaffold . --slug=research --name="Research Hub" --mode=hybrid
+ *   aioson squad:scaffold . --slug=dev-core --name="Dev Core" --mode=software
+ *   aioson squad:scaffold . --slug=research --name="Research Hub" --mode=research
+ *   aioson squad:scaffold . --slug=studio --name="Studio" --mode=mixed
  *   aioson squad:scaffold . --slug=test --json
  */
 
@@ -17,7 +18,7 @@ async function runSquadScaffold({ args, options = {}, logger }) {
   const targetDir = path.resolve(process.cwd(), args[0] || '.');
   const slug = String(options.slug || '').trim();
   const name = String(options.name || slug || '').trim();
-  const mode = String(options.mode || 'hybrid').trim();
+  const mode = String(options.mode || 'mixed').trim();
 
   if (!slug) {
     logger.error('Error: --slug is required');

package/src/commands/squad-score.js

@@ -10,6 +10,55 @@ async function readJsonIfExists(filePath) {
   } catch { return null; }
 }
 
+async function resolveInvestigationEvidence(projectDir, slug, manifest) {
+  const investigation = manifest && typeof manifest.investigation === 'object'
+    ? manifest.investigation
+    : null;
+
+  if (investigation && (investigation.slug || investigation.path)) {
+    const relPath = investigation.path
+      ? String(investigation.path).replace(/\\/g, '/').replace(/^\.\//, '')
+      : null;
+    let existsOnDisk = false;
+    if (relPath) {
+      try {
+        await fs.access(path.resolve(projectDir, relPath));
+        existsOnDisk = true;
+      } catch {
+        existsOnDisk = false;
+      }
+    }
+
+    return {
+      present: true,
+      source: 'manifest',
+      slug: investigation.slug || slug,
+      path: relPath,
+      existsOnDisk
+    };
+  }
+
+  const legacyDir = path.join(projectDir, 'squad-searches', slug);
+  try {
+    await fs.access(legacyDir);
+    return {
+      present: true,
+      source: 'legacy-dir',
+      slug,
+      path: path.relative(projectDir, legacyDir).replace(/\\/g, '/'),
+      existsOnDisk: true
+    };
+  } catch {
+    return {
+      present: false,
+      source: null,
+      slug: null,
+      path: null,
+      existsOnDisk: false
+    };
+  }
+}
+
 function scoreCompletude(manifest) {
   let score = 0;
   const details = {};
@@ -37,7 +86,10 @@ function scoreCompletude(manifest) {
   if (hasWorker) { score += 2; details.workersPresent = true; }
 
   // Investigation report (3pts)
-  if (manifest._investigationPath) { score += 3; details.investigationReport = true; }
+  if (manifest._hasInvestigation) {
+    score += 3;
+    details.investigationReport = manifest._investigationSource || true;
+  }
 
   // Model tiering (2pts)
   const allTiered = executors.length > 0 && executors.every(e => e.modelTier);
@@ -139,7 +191,10 @@ function scorePotencial(manifest) {
   if (hasVeto) { score += 5; details.antiPatternGuards = true; }
 
   // Domain vocabulary — investigation (5pts)
-  if (manifest._investigationPath) { score += 5; details.domainVocabulary = true; }
+  if (manifest._hasInvestigation) {
+    score += 5;
+    details.domainVocabulary = manifest._investigationSource || true;
+  }
 
   // Structural patterns — content blueprints (5pts)
   const blueprints = Array.isArray(manifest.contentBlueprints) ? manifest.contentBlueprints : [];
@@ -187,12 +242,10 @@ async function runSquadScore({ args = [], options = {}, logger = console, transl
     return { valid: false, error: 'Manifest not found' };
   }
 
-  // Check for investigation
-  const squadSearchDir = path.join(projectDir, 'squad-searches', slug);
-  try {
-    await fs.access(squadSearchDir);
-    manifest._investigationPath = squadSearchDir;
-  } catch { /* no investigation */ }
+  const investigationEvidence = await resolveInvestigationEvidence(projectDir, slug, manifest);
+  manifest._hasInvestigation = investigationEvidence.present;
+  manifest._investigationSource = investigationEvidence.source;
+  manifest._investigationPath = investigationEvidence.path;
 
   const d1 = scoreCompletude(manifest);
   const d2 = scoreProfundidade(manifest);
@@ -229,12 +282,16 @@ async function runSquadScore({ args = [], options = {}, logger = console, transl
   try {
     const { openRuntimeDb } = require('../runtime-store');
     const { db } = openRuntimeDb(projectDir);
-    const now = new Date().toISOString();
-    const stmt = db.prepare('INSERT OR REPLACE INTO squad_scores (squad_slug, dimension, score, max_score, details_json, scored_at) VALUES (?, ?, ?, ?, ?, ?)');
-    stmt.run(slug, 'completude', d1.score, d1.max, JSON.stringify(d1.details), now);
-    stmt.run(slug, 'profundidade', d2.score, d2.max, JSON.stringify(d2.details), now);
-    stmt.run(slug, 'qualidade', d3.score, d3.max, JSON.stringify(d3.details), now);
-    stmt.run(slug, 'potencial', d4.score, d4.max, JSON.stringify(d4.details), now);
+    try {
+      const now = new Date().toISOString();
+      const stmt = db.prepare('INSERT OR REPLACE INTO squad_scores (squad_slug, dimension, score, max_score, details_json, scored_at) VALUES (?, ?, ?, ?, ?, ?)');
+      stmt.run(slug, 'completude', d1.score, d1.max, JSON.stringify(d1.details), now);
+      stmt.run(slug, 'profundidade', d2.score, d2.max, JSON.stringify(d2.details), now);
+      stmt.run(slug, 'qualidade', d3.score, d3.max, JSON.stringify(d3.details), now);
+      stmt.run(slug, 'potencial', d4.score, d4.max, JSON.stringify(d4.details), now);
+    } finally {
+      db.close();
+    }
   } catch { /* runtime not available */ }
 
   return {

package/src/commands/squad-status.js

@@ -239,6 +239,9 @@ async function buildSquadRecordFromPackageDir(targetDir, slug) {
   const summaryContent = await fs.readFile(summaryPath, 'utf8').catch(() => null);
   const rules = manifest.rules && typeof manifest.rules === 'object' ? manifest.rules : {};
   const packageInfo = manifest.package && typeof manifest.package === 'object' ? manifest.package : {};
+  const investigation = manifest.investigation && typeof manifest.investigation === 'object'
+    ? manifest.investigation
+    : null;
   const agentsDir = normalizeRel(packageInfo.agentsDir || path.join(SQUADS_DIR, slug, 'agents'));
   const outputDir = normalizeRel(rules.outputsDir || `${OUTPUT_ROOT}/${slug}`);
   const logsDir = normalizeRel(rules.logsDir || `${normalizeRel(LOGS_ROOT)}/${slug}`);
@@ -308,7 +311,13 @@ async function buildSquadRecordFromPackageDir(targetDir, slug) {
         : '—',
     mtime: latestHtml?.mtime || manifestStat?.mtime || null,
     tierSummary: buildTierSummary(manifest.executors),
-    estimatedCost: estimateRunCost(manifest.executors)
+    estimatedCost: estimateRunCost(manifest.executors),
+    localeScope: String(manifest.locale_scope || 'universal'),
+    localeRationale: manifest.locale_rationale || null,
+    domainTier: manifest.domainClassification?.tier || null,
+    investigationSlug: investigation?.slug || null,
+    investigationPath: investigation?.path ? normalizeRel(investigation.path) : null,
+    sourceDocsCount: Array.isArray(manifest.sourceDocs) ? manifest.sourceDocs.length : 0
   };
 }
 
@@ -446,6 +455,18 @@ async function runSquadStatus({ args, logger, t }) {
     if (squad.estimatedCost != null) {
       logger.log(t('squad_status.estimated_cost', { value: squad.estimatedCost.toFixed(3) }));
     }
+    if (squad.localeScope) {
+      logger.log(`  Locale scope: ${squad.localeScope}${squad.localeRationale ? ` — ${squad.localeRationale}` : ''}`);
+    }
+    if (squad.domainTier) {
+      logger.log(`  Domain tier: ${squad.domainTier}`);
+    }
+    if (squad.investigationSlug) {
+      logger.log(`  Investigation: ${squad.investigationSlug}${squad.investigationPath ? ` → ${squad.investigationPath}` : ''}`);
+    }
+    if (squad.sourceDocsCount > 0) {
+      logger.log(`  Source docs: ${squad.sourceDocsCount}`);
+    }
     if (i < squads.length - 1) logger.log('');
   }
 

package/src/commands/squad-validate.js

@@ -14,6 +14,14 @@ async function readJsonIfExists(filePath) {
   } catch { return null; }
 }
 
+function normalizeRelPath(relPath) {
+  return String(relPath || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+}
+
+function isLocaleSpecific(localeScope) {
+  return Boolean(localeScope && localeScope !== 'universal');
+}
+
 function validateManifestFields(manifest) {
   const errors = [];
   const warnings = [];
@@ -33,6 +41,18 @@ function validateManifestFields(manifest) {
     warnings.push(`Unknown mode: "${manifest.mode}"`);
   }
 
+  if (manifest.locale_scope && !/^(universal|[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*)$/.test(manifest.locale_scope)) {
+    errors.push(`Invalid locale_scope: "${manifest.locale_scope}"`);
+  }
+
+  if (!manifest.package || typeof manifest.package !== 'object') {
+    warnings.push('Missing package object — squad uses legacy manifest contract');
+  }
+
+  if (!manifest.rules || typeof manifest.rules !== 'object') {
+    warnings.push('Missing rules object — squad uses legacy manifest contract');
+  }
+
   return { errors, warnings };
 }
 
@@ -77,9 +97,10 @@ async function validateStructure(projectDir, slug, manifest) {
   }
 
   // Check output dir (warning only)
-  const outputDir = path.join(projectDir, 'output', slug);
+  const outputRel = normalizeRelPath(manifest?.rules?.outputsDir || `output/${slug}`);
+  const outputDir = path.join(projectDir, outputRel);
   if (!(await pathExists(outputDir))) {
-    warnings.push(`Output directory not found: output/${slug}/`);
+    warnings.push(`Output directory not found: ${outputRel}/`);
   }
 
   return { errors, warnings };
@@ -267,6 +288,76 @@ async function validateSemanticDeep(projectDir, slug, manifest) {
     }
   }
 
+  // 8. Canonical package contract
+  const packageInfo = manifest.package && typeof manifest.package === 'object' ? manifest.package : {};
+  const rules = manifest.rules && typeof manifest.rules === 'object' ? manifest.rules : {};
+  const canonicalPaths = [
+    ['package.rootDir', packageInfo.rootDir, `.aioson/squads/${slug}`],
+    ['package.agentsDir', packageInfo.agentsDir, `.aioson/squads/${slug}/agents`],
+    ['package.workersDir', packageInfo.workersDir, `.aioson/squads/${slug}/workers`],
+    ['package.workflowsDir', packageInfo.workflowsDir, `.aioson/squads/${slug}/workflows`],
+    ['package.checklistsDir', packageInfo.checklistsDir, `.aioson/squads/${slug}/checklists`],
+    ['package.skillsDir', packageInfo.skillsDir, `.aioson/squads/${slug}/skills`],
+    ['package.templatesDir', packageInfo.templatesDir, `.aioson/squads/${slug}/templates`],
+    ['package.docsDir', packageInfo.docsDir, `.aioson/squads/${slug}/docs`],
+    ['rules.outputsDir', rules.outputsDir, `output/${slug}`],
+    ['rules.logsDir', rules.logsDir, `aioson-logs/${slug}`],
+    ['rules.mediaDir', rules.mediaDir, `media/${slug}`]
+  ];
+
+  for (const [label, actual, expected] of canonicalPaths) {
+    if (!actual) {
+      warnings.push(`Missing ${label} — expected "${expected}"`);
+      continue;
+    }
+    if (normalizeRelPath(actual) !== expected) {
+      warnings.push(`${label} points to "${actual}" instead of canonical "${expected}"`);
+    }
+  }
+
+  // 9. Locale policy validation
+  if (isLocaleSpecific(manifest.locale_scope) && !manifest.locale_rationale) {
+    warnings.push(`locale_scope "${manifest.locale_scope}" is locale-specific but locale_rationale is missing`);
+  }
+
+  // 10. Source docs validation
+  const sourceDocs = Array.isArray(manifest.sourceDocs) ? manifest.sourceDocs : [];
+  for (const docPath of sourceDocs) {
+    const absPath = path.join(projectDir, normalizeRelPath(docPath));
+    if (!(await pathExists(absPath))) {
+      warnings.push(`sourceDocs entry not found: ${docPath}`);
+    }
+  }
+
+  // 11. Investigation validation
+  const investigation = manifest.investigation && typeof manifest.investigation === 'object'
+    ? manifest.investigation
+    : null;
+  const domainClassification = manifest.domainClassification && typeof manifest.domainClassification === 'object'
+    ? manifest.domainClassification
+    : null;
+
+  if (investigation) {
+    if (!investigation.slug) {
+      warnings.push('investigation object is missing "slug"');
+    }
+    if (investigation.path) {
+      const investigationPath = path.join(projectDir, normalizeRelPath(investigation.path));
+      if (!(await pathExists(investigationPath))) {
+        warnings.push(`investigation.path not found: ${investigation.path}`);
+      }
+    } else {
+      warnings.push('investigation object is missing "path"');
+    }
+  }
+
+  const investigationRequired = domainClassification?.tier === 'tier-1-regulated'
+    || domainClassification?.investigationPolicy === 'required';
+
+  if (investigationRequired && !manifest.ephemeral && !investigation) {
+    errors.push('Regulated squad is missing required investigation metadata');
+  }
+
   return { errors, warnings };
 }