@jaimevalasek/aioson 1.28.1 → 1.30.0

package/src/handoff-contract.js

@@ -8,8 +8,9 @@
  * sessions early instead of discovering missing artifacts later.
  */
 
-const path = require('node:path');
-const { readFileSafe, fileExists } = require('./preflight-engine');
+const path = require('node:path');
+const { readFileSafe, fileExists } = require('./preflight-engine');
+const { auditAcceptanceCriteriaTests } = require('./lib/ac-test-audit');
 
 // Contract definitions per agent stage
 const CONTRACTS = {
@@ -373,7 +374,7 @@ async function validateHandoffContract(targetDir, state, stageName) {
   }
 
   // 2. Gates
-  for (const gateLetter of contract.gates) {
+  for (const gateLetter of contract.gates) {
     const gateCheck = await checkGateApproval(
       targetDir,
       gateLetter,
@@ -384,9 +385,16 @@ async function validateHandoffContract(targetDir, state, stageName) {
     if (!gateCheck.ok) {
       missing.push(`gate ${gateLetter} not approved (${gateCheck.reason})`);
     }
-  }
-
-  // 3. Context updates (soft check — just warn if completely missing)
+  }
+
+  if (stageName === 'qa' && state.featureSlug) {
+    const acAudit = await auditAcceptanceCriteriaTests(targetDir, state.featureSlug);
+    if (!acAudit.ok) {
+      missing.push(`AC test audit failed: missing tests for ${acAudit.missing.join(', ')}`);
+    }
+  }
+
+  // 3. Context updates (soft check — just warn if completely missing)
   for (const p of contract.contextUpdates) {
     const abs = path.join(targetDir, p);
     if (!(await fileExists(abs))) {

package/src/harness/contract-schema.js

@@ -144,7 +144,7 @@ function validateContract(contract) {
 
   if (contract.contract_mode !== undefined) {
     if (typeof contract.contract_mode !== 'string' || !VALID_MODES.has(contract.contract_mode.toLowerCase())) {
-      errors.push({ field: 'contract_mode', reason: 'must be one of: BALANCED, safe, builder, autopilot' });
+      errors.push({ field: 'contract_mode', reason: 'must be one of: balanced, safe, builder, autopilot' });
     }
   }
 

package/src/i18n/messages/en.js

@@ -13,9 +13,10 @@ module.exports = {
     help_setup:
       'aioson setup [path] [--defaults] [--framework=<name>] [--lang=<bcp47-tag>] [--project-name=<name>] [--force] [--dry-run] [--tool=codex|claude|opencode] [--locale=en]',
     help_update: 'aioson update [path] [--dry-run] [--lang=<bcp47-tag>] [--locale=en]',
-    help_info: 'aioson info [path] [--json] [--locale=en]',
-    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=en]',
-    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=en]',
+    help_info: 'aioson info [path] [--json] [--locale=en]',
+    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=en]',
+    help_hygiene_scan: 'aioson hygiene:scan [path] [--json] [--locale=en]',
+    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=en]',
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=en]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=en]',
@@ -28,8 +29,14 @@ module.exports = {
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=en]',
     help_context_pack:
       'aioson context:pack [path] [--agent=<agent>] [--goal=<text>] [--module=<module-or-folder>] [--max-files=8] [--json] [--locale=en]',
+    help_context_search:
+      'aioson context:search [path] --query=<text> [--agent=<agent>] [--mode=planning|executing] [--task=<text>] [--paths=<path[,path2]>] [--intent=memory|feature|rules] [--limit=10] [--json] [--locale=en]',
     help_context_select:
-      'aioson context:select [path] [--agent=<agent>] [--mode=planning|executing] [--task=<text>] [--paths=<path[,path2]>] [--feature=<slug>] [--json] [--locale=en]',
+      'aioson context:select [path] [--agent=<agent>] [--mode=planning|executing] [--task=<text>] [--paths=<path[,path2]>] [--feature=<slug>] [--no-semantic] [--json] [--locale=en]',
+    help_context_brief:
+      'aioson context:brief [path] [--agent=<agent>] [--mode=planning|executing] [--task=<text>] [--paths=<path[,path2]>] [--feature=<slug>] [--no-semantic] [--no-recall] [--json] [--locale=en]',
+    help_context_guard:
+      'aioson context:guard [path] [--tool=claude] [--agent=<agent>] [--event=<json>] [--event-file=<path>] [--json] [--locale=en]',
     help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<name> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=en]',
     help_chain_audit:
@@ -153,7 +160,7 @@ module.exports = {
     help_qa_report:
       'aioson qa:report [path] [--html] [--json] [--locale=en]',
     help_harness_init:
-      'aioson harness:init [path] --slug=<slug> [--mode=BALANCED|URGENT|ECONOMICAL] [--locale=en]',
+      'aioson harness:init [path] --slug=<slug> [--mode=balanced|safe|builder|autopilot] [--locale=en]',
     help_harness_validate:
       'aioson harness:validate [path] --slug=<slug> [--base=<ref>] [--no-diff] [--max-diff-bytes=<n>] [--artifact=<path>] [--locale=en]',
     help_harness_check:

package/src/i18n/messages/es.js

@@ -14,9 +14,10 @@ module.exports = {
       'aioson setup [path] [--defaults] [--framework=<nombre>] [--lang=<bcp47-tag>] [--project-name=<nombre>] [--force] [--dry-run] [--tool=codex|claude|opencode] [--locale=es]',
     help_update:
       'aioson update [path] [--dry-run] [--lang=<bcp47-tag>] [--locale=es]',
-    help_info: 'aioson info [path] [--json] [--locale=es]',
-    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=es]',
-    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=es]',
+    help_info: 'aioson info [path] [--json] [--locale=es]',
+    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=es]',
+    help_hygiene_scan: 'aioson hygiene:scan [path] [--json] [--locale=es]',
+    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=es]',
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=es]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=es]',
@@ -29,8 +30,14 @@ module.exports = {
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=es]',
     help_context_pack:
       'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-o-carpeta>] [--max-files=8] [--json] [--locale=es]',
+    help_context_search:
+      'aioson context:search [path] --query=<texto> [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<ruta[,ruta2]>] [--intent=memory|feature|rules] [--limit=10] [--json] [--locale=es]',
     help_context_select:
-      'aioson context:select [path] [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<ruta[,ruta2]>] [--feature=<slug>] [--json] [--locale=es]',
+      'aioson context:select [path] [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<ruta[,ruta2]>] [--feature=<slug>] [--no-semantic] [--json] [--locale=es]',
+    help_context_brief:
+      'aioson context:brief [path] [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<ruta[,ruta2]>] [--feature=<slug>] [--no-semantic] [--no-recall] [--json] [--locale=es]',
+    help_context_guard:
+      'aioson context:guard [path] [--tool=claude] [--agent=<agente>] [--event=<json>] [--event-file=<ruta>] [--json] [--locale=es]',
     help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nombre> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=es]',
     help_chain_audit:

package/src/i18n/messages/fr.js

@@ -14,9 +14,10 @@ module.exports = {
       'aioson setup [path] [--defaults] [--framework=<nom>] [--lang=<bcp47-tag>] [--project-name=<nom>] [--force] [--dry-run] [--tool=codex|claude|opencode] [--locale=fr]',
     help_update:
       'aioson update [path] [--dry-run] [--lang=<bcp47-tag>] [--locale=fr]',
-    help_info: 'aioson info [path] [--json] [--locale=fr]',
-    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=fr]',
-    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=fr]',
+    help_info: 'aioson info [path] [--json] [--locale=fr]',
+    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=fr]',
+    help_hygiene_scan: 'aioson hygiene:scan [path] [--json] [--locale=fr]',
+    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=fr]',
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=fr]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=fr]',
@@ -29,8 +30,14 @@ module.exports = {
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=fr]',
     help_context_pack:
       'aioson context:pack [path] [--agent=<agent>] [--goal=<texte>] [--module=<module-ou-dossier>] [--max-files=8] [--json] [--locale=fr]',
+    help_context_search:
+      'aioson context:search [path] --query=<texte> [--agent=<agent>] [--mode=planning|executing] [--task=<texte>] [--paths=<chemin[,chemin2]>] [--intent=memory|feature|rules] [--limit=10] [--json] [--locale=fr]',
     help_context_select:
-      'aioson context:select [path] [--agent=<agent>] [--mode=planning|executing] [--task=<texte>] [--paths=<chemin[,chemin2]>] [--feature=<slug>] [--json] [--locale=fr]',
+      'aioson context:select [path] [--agent=<agent>] [--mode=planning|executing] [--task=<texte>] [--paths=<chemin[,chemin2]>] [--feature=<slug>] [--no-semantic] [--json] [--locale=fr]',
+    help_context_brief:
+      'aioson context:brief [path] [--agent=<agent>] [--mode=planning|executing] [--task=<texte>] [--paths=<chemin[,chemin2]>] [--feature=<slug>] [--no-semantic] [--no-recall] [--json] [--locale=fr]',
+    help_context_guard:
+      'aioson context:guard [path] [--tool=claude] [--agent=<agent>] [--event=<json>] [--event-file=<chemin>] [--json] [--locale=fr]',
     help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nom> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=fr]',
     help_chain_audit:

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

@@ -14,9 +14,10 @@ module.exports = {
       'aioson setup [path] [--defaults] [--framework=<nome>] [--lang=<bcp47-tag>] [--project-name=<nome>] [--force] [--dry-run] [--tool=codex|claude|opencode] [--locale=pt-BR]',
     help_update:
       'aioson update [path] [--dry-run] [--lang=<bcp47-tag>] [--locale=pt-BR]',
-    help_info: 'aioson info [path] [--json] [--locale=pt-BR]',
-    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=pt-BR]',
-    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=pt-BR]',
+    help_info: 'aioson info [path] [--json] [--locale=pt-BR]',
+    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=pt-BR]',
+    help_hygiene_scan: 'aioson hygiene:scan [path] [--json] [--locale=pt-BR]',
+    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=pt-BR]',
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=pt-BR]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=pt-BR]',
@@ -29,8 +30,14 @@ module.exports = {
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=pt-BR]',
     help_context_pack:
       'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-ou-pasta>] [--max-files=8] [--json] [--locale=pt-BR]',
+    help_context_search:
+      'aioson context:search [path] --query=<texto> [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<caminho[,caminho2]>] [--intent=memory|feature|rules] [--limit=10] [--json] [--locale=pt-BR]',
     help_context_select:
-      'aioson context:select [path] [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<caminho[,caminho2]>] [--feature=<slug>] [--json] [--locale=pt-BR]',
+      'aioson context:select [path] [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<caminho[,caminho2]>] [--feature=<slug>] [--no-semantic] [--json] [--locale=pt-BR]',
+    help_context_brief:
+      'aioson context:brief [path] [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<caminho[,caminho2]>] [--feature=<slug>] [--no-semantic] [--no-recall] [--json] [--locale=pt-BR]',
+    help_context_guard:
+      'aioson context:guard [path] [--tool=claude] [--agent=<agente>] [--event=<json>] [--event-file=<caminho>] [--json] [--locale=pt-BR]',
     help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nome> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=pt-BR]',
     help_chain_audit:
@@ -155,7 +162,7 @@ module.exports = {
     help_qa_report:
       'aioson qa:report [path] [--html] [--json] [--locale=pt-BR]',
     help_harness_init:
-      'aioson harness:init [path] --slug=<slug> [--mode=BALANCED|URGENT|ECONOMICAL] [--locale=pt-BR]',
+      'aioson harness:init [path] --slug=<slug> [--mode=balanced|safe|builder|autopilot] [--locale=pt-BR]',
     help_harness_validate:
       'aioson harness:validate [path] --slug=<slug> [--base=<ref>] [--no-diff] [--max-diff-bytes=<n>] [--artifact=<path>] [--locale=pt-BR]',
     help_harness_check:

package/src/lib/ac-test-audit.js

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * ac-test-audit — deterministic AC→test evidence audit (no LLM).
+ *
+ * `AC_ID_RE` is the single canonical AC identifier pattern; spec-analyze and
+ * artifact-validate import it so all three surfaces extract the same IDs
+ * (case-insensitive segments cover slugged ids like AC-checkout-01).
+ *
+ * Matching contract & known limitations (kept honest on purpose):
+ * - Evidence is a token-boundary mention of the AC id in a test file or in an
+ *   executable harness criterion. `mentionsAcId` matches whole hyphen-delimited
+ *   tokens so AC-1 does NOT match inside AC-10 (substring collision).
+ * - It cannot judge assertion strength: any token-boundary mention counts, so a
+ *   weak/empty test or a comment that names the AC reads as covered. The
+ *   harness `verification` path is the stronger evidence.
+ * - A test that exercises an AC's behaviour without naming the id reads as
+ *   missing — the audit enforces the "cite the AC in its test" convention.
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const AC_ID_RE = /\bAC(?:-[A-Za-z0-9]+)+\b/g;
+const TEST_FILE_RE = /(?:^|[\\/])(?:tests?|__tests__)[\\/].+\.(?:test|spec)\.(?:js|cjs|mjs|ts|tsx|jsx)$|(?:^|[\\/])[^\\/]+\.(?:test|spec)\.(?:js|cjs|mjs|ts|tsx|jsx)$/i;
+
+function extractAcIds(content) {
+  return [...new Set(String(content || '').match(AC_ID_RE) || [])].sort();
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Whole-token match: the id must not be flanked by word chars or hyphens, so
+// AC-1 will not match inside AC-10 / AC-100 and AC-SDLC-1 not inside AC-SDLC-10.
+function mentionsAcId(text, acId) {
+  return new RegExp(`(?<![\\w-])${escapeRegExp(acId)}(?![\\w-])`).test(String(text || ''));
+}
+
+async function readText(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function toRel(targetDir, filePath) {
+  return path.relative(targetDir, filePath).split(path.sep).join('/');
+}
+
+function shouldSkipDir(targetDir, dirPath) {
+  const rel = toRel(targetDir, dirPath);
+  return rel.split('/').some((part, idx, parts) => {
+    if (part === 'node_modules' || part === '.git' || part === 'dist' || part === 'build' || part === 'coverage') return true;
+    return idx > 0 && parts[idx - 1] === '.aioson' && part === 'backups';
+  });
+}
+
+async function listTestFiles(targetDir, dirPath = targetDir, out = []) {
+  let entries;
+  try {
+    entries = await fs.readdir(dirPath, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+
+  for (const entry of entries) {
+    const full = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      if (!shouldSkipDir(targetDir, full)) await listTestFiles(targetDir, full, out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const rel = toRel(targetDir, full);
+    if (TEST_FILE_RE.test(rel)) out.push(full);
+  }
+  return out;
+}
+
+function testEvidenceFor(acId, testContents) {
+  return testContents
+    .filter((item) => mentionsAcId(item.content, acId))
+    .map((item) => ({
+      file: item.file,
+      evidence: `test file references ${acId}`
+    }));
+}
+
+function harnessEvidenceFor(acId, contract) {
+  if (!contract || !Array.isArray(contract.criteria)) return [];
+  return contract.criteria
+    .filter((criterion) => {
+      if (!criterion || typeof criterion !== 'object') return false;
+      const text = JSON.stringify(criterion);
+      return mentionsAcId(text, acId) && typeof criterion.verification === 'string' && criterion.verification.trim();
+    })
+    .map((criterion) => ({
+      file: '.aioson/plans/{slug}/harness-contract.json',
+      criterion: criterion.id,
+      evidence: `executable harness criterion references ${acId}`
+    }));
+}
+
+async function readHarnessContract(targetDir, slug) {
+  const contractPath = path.join(targetDir, '.aioson', 'plans', slug, 'harness-contract.json');
+  const raw = await readText(contractPath);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function collectAcceptanceCriteria(targetDir, slug) {
+  const contextDir = path.join(targetDir, '.aioson', 'context');
+  const sources = [
+    { kind: 'requirements', path: path.join(contextDir, `requirements-${slug}.md`) },
+    { kind: 'prd', path: path.join(contextDir, `prd-${slug}.md`) },
+    { kind: 'conformance', path: path.join(contextDir, `conformance-${slug}.yaml`) }
+  ];
+
+  const byId = new Map();
+  for (const source of sources) {
+    const content = await readText(source.path);
+    if (!content) continue;
+    for (const id of extractAcIds(content)) {
+      if (!byId.has(id)) {
+        byId.set(id, { id, sources: [] });
+      }
+      byId.get(id).sources.push({
+        kind: source.kind,
+        file: toRel(targetDir, source.path)
+      });
+    }
+  }
+
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+async function auditAcceptanceCriteriaTests(targetDir, slug) {
+  const criteria = await collectAcceptanceCriteria(targetDir, slug);
+  const testFiles = await listTestFiles(targetDir);
+  const testContents = [];
+  for (const filePath of testFiles) {
+    const content = await readText(filePath);
+    if (content !== null) {
+      testContents.push({ file: toRel(targetDir, filePath), content });
+    }
+  }
+
+  const contract = await readHarnessContract(targetDir, slug);
+  const items = criteria.map((criterion) => {
+    const testEvidence = testEvidenceFor(criterion.id, testContents);
+    const harnessEvidence = harnessEvidenceFor(criterion.id, contract).map((e) => ({
+      ...e,
+      file: e.file.replace('{slug}', slug)
+    }));
+    const evidence = [...testEvidence, ...harnessEvidence];
+    return {
+      ac: criterion.id,
+      status: evidence.length > 0 ? 'covered' : 'missing',
+      sources: criterion.sources,
+      evidence
+    };
+  });
+
+  const missing = items.filter((item) => item.status === 'missing');
+  const summary = {
+    acs_total: items.length,
+    covered: items.filter((item) => item.status === 'covered').length,
+    missing: missing.length,
+    test_files_scanned: testContents.length
+  };
+
+  return {
+    ok: missing.length === 0,
+    feature: slug,
+    audited_at: new Date().toISOString(),
+    summary,
+    items,
+    missing: missing.map((item) => item.ac)
+  };
+}
+
+module.exports = {
+  AC_ID_RE,
+  extractAcIds,
+  mentionsAcId,
+  collectAcceptanceCriteria,
+  auditAcceptanceCriteriaTests
+};

package/src/preflight-engine.js

@@ -257,10 +257,11 @@ async function scanArtifacts(targetDir, slug) {
     : [path.join(dir, 'readiness.md')];
 
   const results = {
-    project_context: await check('project.context', path.join(dir, 'project.context.md')),
-    prd: slug ? await check('prd', path.join(dir, `prd-${slug}.md`)) : { exists: false },
-    sheldon_enrichment: slug ? await check('sheldon', path.join(dir, `sheldon-enrichment-${slug}.md`)) : { exists: false },
-    requirements: slug ? await check('requirements', path.join(dir, `requirements-${slug}.md`)) : { exists: false },
+    project_context: await check('project.context', path.join(dir, 'project.context.md')),
+    prd: slug ? await check('prd', path.join(dir, `prd-${slug}.md`)) : { exists: false },
+    sheldon_enrichment: slug ? await check('sheldon', path.join(dir, `sheldon-enrichment-${slug}.md`)) : { exists: false },
+    sheldon_validation: slug ? await check('sheldon-validation', path.join(dir, `sheldon-validation-${slug}.md`)) : { exists: false },
+    requirements: slug ? await check('requirements', path.join(dir, `requirements-${slug}.md`)) : { exists: false },
     spec: slug ? await check('spec', path.join(dir, `spec-${slug}.md`)) : await check('spec', path.join(dir, 'spec.md')),
     architecture: await check('architecture', path.join(dir, 'architecture.md')),
     design_doc: await checkFirst('design-doc', designDocCandidates),
@@ -479,8 +480,11 @@ function buildContextPackage(agent, slug, classification, artifacts, devState, m
     const downstreamAgents = ['discovery-design-doc', 'pm', 'orchestrator', 'dev', 'deyvin', 'qa'];
     const shouldCarryFullFeatureContext = downstreamAgents.includes(agent);
 
-    if (shouldCarryFullFeatureContext && artifacts.prd.exists) pkg.push(artifacts.prd.path);
-    if (shouldCarryFullFeatureContext && artifacts.sheldon_enrichment.exists) pkg.push(artifacts.sheldon_enrichment.path);
+    if (shouldCarryFullFeatureContext && artifacts.prd.exists) pkg.push(artifacts.prd.path);
+    if (shouldCarryFullFeatureContext && artifacts.sheldon_enrichment.exists) pkg.push(artifacts.sheldon_enrichment.path);
+    if (shouldCarryFullFeatureContext && artifacts.sheldon_validation && artifacts.sheldon_validation.exists) {
+      pkg.push(artifacts.sheldon_validation.path);
+    }
     if ((shouldCarryFullFeatureContext || ['analyst', 'architect'].includes(agent)) && artifacts.requirements.exists) {
       pkg.push(artifacts.requirements.path);
     }

package/src/squad/state-manager.js

@@ -6,7 +6,7 @@
  * Maintains a cross-session memory file per squad at:
  *   .aioson/squads/{slug}/STATE.md
  *
- * The STATE.md survives /clear and gives the next session instant context on:
+ * The STATE.md survives /compact or /clear and gives the next session instant context on:
  *   - Current position in the squad's lifecycle
  *   - Velocity metrics
  *   - Active blockers