@jaimevalasek/aioson 1.7.2 → 1.8.0

package/src/dossier/store.js

@@ -0,0 +1,400 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const {
+  SCHEMA_VERSION,
+  REQUIRED_SECTIONS,
+  isValidSlug,
+  assertFrontmatter,
+  validateFrontmatter
+} = require('./schema');
+
+const FEATURES_SUBDIR = 'features';
+const DOSSIER_FILENAME = 'dossier.md';
+const DEFAULT_AUTHOR = 'dossier-init';
+
+function featureDir(contextDir, slug) {
+  return path.join(contextDir, FEATURES_SUBDIR, slug);
+}
+
+function dossierPath(contextDir, slug) {
+  return path.join(featureDir(contextDir, slug), DOSSIER_FILENAME);
+}
+
+function prdPath(contextDir, slug) {
+  return path.join(contextDir, `prd-${slug}.md`);
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseFrontmatter(markdown) {
+  const text = String(markdown || '');
+  if (!text.startsWith('---\n') && !text.startsWith('---\r\n')) {
+    return { ok: false, data: null, body: text, reason: 'missing_frontmatter' };
+  }
+  const lines = text.split(/\r?\n/);
+  let closingIndex = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') {
+      closingIndex = i;
+      break;
+    }
+  }
+  if (closingIndex === -1) {
+    return { ok: false, data: null, body: text, reason: 'unclosed_frontmatter' };
+  }
+  const data = {};
+  for (let i = 1; i < closingIndex; i += 1) {
+    const line = lines[i].trim();
+    if (!line || line.startsWith('#')) continue;
+    const match = line.match(/^([a-zA-Z0-9_]+)\s*:\s*(.*)$/);
+    if (!match) {
+      return { ok: false, data: null, body: text, reason: 'invalid_frontmatter_line', line };
+    }
+    let val = match[2].trim();
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    data[match[1]] = val;
+  }
+  const body = lines.slice(closingIndex + 1).join('\n');
+  return { ok: true, data, body };
+}
+
+function parseSections(markdown) {
+  const text = String(markdown || '');
+  const parsed = parseFrontmatter(text);
+  const body = parsed.ok ? parsed.body : text;
+  const sections = Object.create(null);
+
+  const lines = body.split(/\r?\n/);
+  let current = null;
+  let buf = [];
+
+  const flush = () => {
+    if (current !== null) {
+      sections[current] = buf.join('\n').replace(/\s+$/, '');
+    }
+  };
+
+  for (const line of lines) {
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      flush();
+      current = m[1].trim();
+      buf = [];
+    } else if (current !== null) {
+      buf.push(line);
+    }
+  }
+  flush();
+
+  return sections;
+}
+
+function extractPrdSection(prdMarkdown, headingNames) {
+  if (!prdMarkdown) return null;
+  const sections = parseSections(prdMarkdown);
+  for (const name of headingNames) {
+    if (sections[name]) {
+      const trimmed = sections[name].trim();
+      if (trimmed) return trimmed;
+    }
+  }
+  return null;
+}
+
+function buildDossierMarkdown({
+  slug,
+  classification,
+  createdAt,
+  author,
+  why,
+  what
+}) {
+  const fm = [
+    '---',
+    `feature_slug: ${slug}`,
+    `schema_version: "${SCHEMA_VERSION}"`,
+    `created_by: ${author}`,
+    `created_at: ${createdAt}`,
+    'status: active',
+    `classification: ${classification}`,
+    `last_updated_by: ${author}`,
+    `last_updated_at: ${createdAt}`,
+    '---',
+    ''
+  ].join('\n');
+
+  const body = [
+    '## Why',
+    '',
+    why || '_(preencher manualmente — PRD não encontrado ou sem seção de Vision/Problem)_',
+    '',
+    '## What',
+    '',
+    what || '_(preencher manualmente — PRD não encontrado ou sem seção de Escopo)_',
+    '',
+    '## Code Map',
+    '',
+    '```yaml',
+    'files: []',
+    'modules: []',
+    'patterns: []',
+    '```',
+    '',
+    '## Rules & Design-Docs aplicáveis',
+    '',
+    '_(vazio — populado a partir da Phase 2)_',
+    '',
+    '## Agent Trail',
+    '',
+    '_(vazio — populado a partir da Phase 2)_',
+    '',
+    '## Revision Requests',
+    '',
+    '_(vazio — populado a partir da Phase 2)_',
+    ''
+  ].join('\n');
+
+  return fm + body;
+}
+
+async function init({
+  slug,
+  contextDir,
+  classification = 'MEDIUM',
+  author = DEFAULT_AUTHOR,
+  now = () => new Date(),
+  prdContent,
+  whyText,
+  whatText
+} = {}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug (must be kebab-case): ${JSON.stringify(slug)}`);
+    err.code = 'EDOSSIERSLUG';
+    throw err;
+  }
+  if (typeof contextDir !== 'string' || !contextDir) {
+    throw new TypeError('init: contextDir must be a non-empty string');
+  }
+
+  const dir = featureDir(contextDir, slug);
+  const filePath = dossierPath(contextDir, slug);
+
+  let prd = prdContent;
+  if (prd === undefined) {
+    const candidate = prdPath(contextDir, slug);
+    if (await fileExists(candidate)) {
+      prd = await fs.readFile(candidate, 'utf8');
+    }
+  }
+
+  const why = whyText !== undefined ? whyText : extractPrdSection(prd, ['Problem', 'Why', 'Vision']);
+  const what = whatText !== undefined ? whatText : extractPrdSection(prd, ['Escopo do MVP', 'Scope', 'What']);
+
+  const createdAt = now().toISOString();
+  const markdown = buildDossierMarkdown({
+    slug,
+    classification,
+    createdAt,
+    author,
+    why,
+    what
+  });
+
+  // Validate before writing — fail fast if our own builder produces invalid output.
+  const fmValidation = validateFrontmatter({
+    feature_slug: slug,
+    schema_version: SCHEMA_VERSION,
+    created_by: author,
+    created_at: createdAt,
+    status: 'active',
+    classification,
+    last_updated_by: author,
+    last_updated_at: createdAt
+  });
+  if (!fmValidation.valid) {
+    const err = new Error(`refusing to write invalid dossier: ${fmValidation.errors.join('; ')}`);
+    err.code = 'EDOSSIERSCHEMA';
+    err.errors = fmValidation.errors;
+    throw err;
+  }
+
+  await fs.mkdir(dir, { recursive: true });
+  let fh;
+  try {
+    fh = await fs.open(filePath, 'wx');
+  } catch (err) {
+    if (err && err.code === 'EEXIST') {
+      const e = new Error(`dossier already exists at ${filePath}`);
+      e.code = 'EDOSSIEREXISTS';
+      e.path = filePath;
+      throw e;
+    }
+    throw err;
+  }
+  try {
+    await fh.writeFile(markdown);
+  } finally {
+    await fh.close();
+  }
+
+  return { path: filePath, dir, frontmatter: fmValidation, sections: parseSections(markdown) };
+}
+
+async function read({ slug, contextDir } = {}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug (must be kebab-case): ${JSON.stringify(slug)}`);
+    err.code = 'EDOSSIERSLUG';
+    throw err;
+  }
+  const filePath = dossierPath(contextDir, slug);
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      const e = new Error(`dossier not found for slug "${slug}" at ${filePath}`);
+      e.code = 'EDOSSIERMISSING';
+      e.path = filePath;
+      throw e;
+    }
+    throw err;
+  }
+
+  const fmParse = parseFrontmatter(raw);
+  if (!fmParse.ok) {
+    const err = new Error(`malformed dossier frontmatter at ${filePath}: ${fmParse.reason}`);
+    err.code = 'EDOSSIERPARSE';
+    err.path = filePath;
+    throw err;
+  }
+
+  // Schema validation — fail loud, never silent.
+  assertFrontmatter(fmParse.data);
+
+  return {
+    path: filePath,
+    raw,
+    frontmatter: fmParse.data,
+    sections: parseSections(raw)
+  };
+}
+
+async function show({ slug, contextDir } = {}) {
+  const { raw, frontmatter, sections, path: p } = await read({ slug, contextDir });
+
+  // Check for corrupted dossier-history.md (if present)
+  let historyWarn = null;
+  const hp = path.join(path.dirname(p), 'dossier-history.md');
+  try {
+    const histRaw = await fs.readFile(hp, 'utf8');
+    if (typeof histRaw !== 'string') historyWarn = 'history_corrupted';
+  } catch (err) {
+    if (err && err.code !== 'ENOENT') historyWarn = 'history_corrupted';
+    // ENOENT = absent, not corrupted — silently ignore
+  }
+
+  const header = [
+    `# Dossier — ${frontmatter.feature_slug} (${frontmatter.classification})`,
+    `status=${frontmatter.status} schema=${frontmatter.schema_version} updated=${frontmatter.last_updated_at}`,
+    `path: ${p}`,
+    ''
+  ].join('\n');
+  return { header, raw, frontmatter, sections, path: p, warn: historyWarn };
+}
+
+// Append-only write to a named ## section in dossier.md.
+// Uses SHA-256 of (section + content) for dedup — repeated calls with same args are no-ops.
+async function addFinding({ slug, contextDir, agent, section, content, now = () => new Date() } = {}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug: ${JSON.stringify(slug)}`);
+    err.code = 'EDOSSIERSLUG';
+    throw err;
+  }
+  const filePath = dossierPath(contextDir, slug);
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      const e = new Error(`dossier not found for slug "${slug}" at ${filePath}`);
+      e.code = 'EDOSSIERMISSING';
+      e.path = filePath;
+      throw e;
+    }
+    throw err;
+  }
+
+  const hash = crypto.createHash('sha256').update(`${section}\0${content}`).digest('hex');
+  const hashMarker = `<!-- sha256:${hash} -->`;
+
+  // Idempotency: if hash already present, no-op silently
+  if (raw.includes(hashMarker)) {
+    return { added: false, hash };
+  }
+
+  const timestamp = now().toISOString();
+  const entry = [
+    hashMarker,
+    `**${timestamp}** | @${agent} | _${section}_`,
+    '',
+    content.trim(),
+    ''
+  ].join('\n');
+
+  // Append inside ## Agent Trail (or after it if not found)
+  const lines = raw.split('\n');
+  let trailEnd = lines.length;
+  let inTrail = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trimEnd() === '## Agent Trail') {
+      inTrail = true;
+    } else if (inTrail && /^## /.test(lines[i])) {
+      trailEnd = i;
+      break;
+    }
+  }
+
+  // Insert before the next section (or at end of file)
+  const before = lines.slice(0, trailEnd);
+  const after = lines.slice(trailEnd);
+
+  // Trim trailing blank lines from before to avoid double blanks
+  while (before.length > 0 && before[before.length - 1].trim() === '') before.pop();
+  before.push('', entry.trimEnd());
+
+  const rebuilt = [...before, '', ...after].join('\n');
+  await fs.writeFile(filePath, rebuilt, 'utf8');
+
+  return { added: true, hash };
+}
+
+module.exports = {
+  FEATURES_SUBDIR,
+  DOSSIER_FILENAME,
+  DEFAULT_AUTHOR,
+  REQUIRED_SECTIONS,
+  featureDir,
+  dossierPath,
+  prdPath,
+  parseFrontmatter,
+  parseSections,
+  buildDossierMarkdown,
+  addFinding,
+  init,
+  read,
+  show
+};

package/src/execution-gateway.js

@@ -220,6 +220,9 @@ async function syncWorkflowRuntime(targetDir, input) {
   try {
     const state = input.state || {};
     const eventPayload = input.eventPayload || {};
+    if (!eventPayload.autonomy_mode && eventPayload.autonomyMode) {
+      eventPayload.autonomy_mode = eventPayload.autonomyMode;
+    }
     const activationAgent = normalizeText(input.activationAgent);
     const completedStage = normalizeText(input.completedStage);
     const sessionKey = makeWorkflowSessionKey(state);

package/src/friction-scanner.js

@@ -0,0 +1,202 @@
+'use strict';
+
+/**
+ * friction-scanner — analyzes workflow error logs to detect recurring friction patterns.
+ *
+ * Reads .aioson/context/workflow.errors.jsonl and produces structured
+ * recommendations for codebase hardening.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const { readFileSafe, fileExists } = require('./preflight-engine');
+
+const ERRORS_PATH = '.aioson/context/workflow.errors.jsonl';
+
+const PATTERNS = [
+  {
+    id: 'typescript_compile',
+    name: 'TypeScript compilation errors',
+    test: (err) => /tsc|typescript|type mismatch|cannot find module|unused import/i.test(err)
+  },
+  {
+    id: 'rust_compile',
+    name: 'Rust compilation errors',
+    test: (err) => /cargo check|rustc|sqlx|actix|tokio/i.test(err)
+  },
+  {
+    id: 'jsx_structure',
+    name: 'JSX / React structure errors',
+    test: (err) => /jsx|react|component|element type is invalid|nested|display-property/i.test(err)
+  },
+  {
+    id: 'test_mock_order',
+    name: 'Mock ordering / test helper issues',
+    test: (err) => /vi\.mock|vi\.fn|jest\.mock|mock ordering|hoisted|getByText/i.test(err)
+  },
+  {
+    id: 'ui_text_mismatch',
+    name: 'UI text mismatch in tests',
+    test: (err) => /confirmar|vincular|button label|tab name|ui text|assertion/i.test(err)
+  },
+  {
+    id: 'git_staging',
+    name: 'Git staging accidents',
+    test: (err) => /node_modules|build artifact|dev\.db|\.next|unwanted files staged/i.test(err)
+  },
+  {
+    id: 'path_misunderstanding',
+    name: 'Path / directory misinterpretation',
+    test: (err) => /wrong directory|path misunderstanding|bootstrap|\.aioson\/docs/i.test(err)
+  },
+  {
+    id: 'handoff_contract',
+    name: 'Handoff contract violations',
+    test: (err) => /handoff contract|missing artifact|gate .* not approved/i.test(err)
+  }
+];
+
+async function loadErrors(targetDir) {
+  const errorsPath = path.join(targetDir, ERRORS_PATH);
+  if (!(await fileExists(errorsPath))) return [];
+  const content = await readFileSafe(errorsPath);
+  if (!content) return [];
+  const lines = content.trim().split('\n').filter(Boolean);
+  const entries = [];
+  for (const line of lines) {
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      // ignore malformed lines
+    }
+  }
+  return entries;
+}
+
+function classifyError(entry) {
+  const text = `${entry.error || ''} ${entry.gateType || ''}`;
+  for (const pattern of PATTERNS) {
+    if (pattern.test(text)) {
+      return pattern.id;
+    }
+  }
+  return 'unknown';
+}
+
+async function scanFriction(targetDir) {
+  const entries = await loadErrors(targetDir);
+  const counts = {};
+  const byPattern = {};
+  const recent = entries.slice(-20);
+
+  for (const entry of entries) {
+    const pid = classifyError(entry);
+    counts[pid] = (counts[pid] || 0) + 1;
+    if (!byPattern[pid]) byPattern[pid] = [];
+    byPattern[pid].push(entry);
+  }
+
+  const sorted = Object.entries(counts)
+    .sort((a, b) => b[1] - a[1])
+    .map(([pid, count]) => {
+      const pattern = PATTERNS.find((p) => p.id === pid);
+      return {
+        id: pid,
+        name: pattern ? pattern.name : pid,
+        count,
+        examples: (byPattern[pid] || []).slice(-3).map((e) => e.error?.substring(0, 200) || '')
+      };
+    });
+
+  return {
+    total: entries.length,
+    recentCount: recent.length,
+    patterns: sorted
+  };
+}
+
+function buildRecommendations(analysis) {
+  const recs = [];
+  for (const p of analysis.patterns) {
+    switch (p.id) {
+      case 'typescript_compile':
+        recs.push({
+          pattern: p.name,
+          action: 'Enable strict type-checking hooks or add "tsc --noEmit" to pre-commit checks.',
+          autoFixable: false,
+          priority: p.count >= 3 ? 'high' : 'medium'
+        });
+        break;
+      case 'rust_compile':
+        recs.push({
+          pattern: p.name,
+          action: 'Add "cargo check" as a mandatory step in the dev agent prompt or CI pipeline.',
+          autoFixable: false,
+          priority: p.count >= 3 ? 'high' : 'medium'
+        });
+        break;
+      case 'jsx_structure':
+        recs.push({
+          pattern: p.name,
+          action: 'Add an ESLint plugin for JSX nesting rules (e.g., eslint-plugin-react).',
+          autoFixable: false,
+          priority: 'medium'
+        });
+        break;
+      case 'test_mock_order':
+        recs.push({
+          pattern: p.name,
+          action: 'Create a shared mock factory in tests/helpers/mocks.ts and update test conventions.',
+          autoFixable: true,
+          priority: p.count >= 2 ? 'high' : 'medium'
+        });
+        break;
+      case 'ui_text_mismatch':
+        recs.push({
+          pattern: p.name,
+          action: 'Enforce the test-briefing injection (already active) and add a rule to prefer getByRole.',
+          autoFixable: false,
+          priority: 'medium'
+        });
+        break;
+      case 'git_staging':
+        recs.push({
+          pattern: p.name,
+          action: 'Ensure .gitignore covers node_modules, dist, .next, *.db and install the pre-commit hook.',
+          autoFixable: true,
+          priority: 'high'
+        });
+        break;
+      case 'path_misunderstanding':
+        recs.push({
+          pattern: p.name,
+          action: 'Verify project-map.md exists and is loaded by implementation agents (already active).',
+          autoFixable: false,
+          priority: 'medium'
+        });
+        break;
+      case 'handoff_contract':
+        recs.push({
+          pattern: p.name,
+          action: 'Review agent prompts to ensure they set the correct gates and produce required artifacts.',
+          autoFixable: false,
+          priority: 'high'
+        });
+        break;
+      default:
+        recs.push({
+          pattern: p.name,
+          action: 'Investigate root cause manually and add a preventive rule.',
+          autoFixable: false,
+          priority: 'low'
+        });
+    }
+  }
+  return recs;
+}
+
+module.exports = {
+  scanFriction,
+  buildRecommendations,
+  PATTERNS
+};

package/src/genome-schema.js

@@ -6,6 +6,7 @@ const {
   GENOME_FORMATS,
   GENOME_CONFIDENCE_LEVELS,
   GENOME_TYPES,
+  GENOME_RELATION_TYPES,
   countGenomeSections,
   normalizeGenome,
   normalizeGenomeMeta
@@ -79,6 +80,18 @@ function validatePersonaV3Requirements(normalized, sections, errors) {
       errors.push(`sections.${key} must contain at least one entry for genome-v3 persona profiles`);
     }
   }
+
+  // track 4.0 — optional, validate only if present
+  if (normalized.hexacoH && !GENOME_CONFIDENCE_LEVELS.includes(normalized.hexacoH)) {
+    errors.push(`hexaco_h must be one of: ${GENOME_CONFIDENCE_LEVELS.join(', ')}`);
+  }
+  if (Array.isArray(normalized.relations)) {
+    for (const rel of normalized.relations) {
+      if (rel.type && !GENOME_RELATION_TYPES.includes(rel.type)) {
+        errors.push(`relations[].type must be one of: ${GENOME_RELATION_TYPES.join(', ')}`);
+      }
+    }
+  }
 }
 
 function validateGenomeObject(input) {
@@ -155,6 +168,7 @@ function validateGenomeMeta(input) {
         cognitiveProfile: Array(meta.counts.cognitiveProfile).fill('x'),
         communicationStyle: Array(meta.counts.communicationStyle).fill('x'),
         biases: Array(meta.counts.biases).fill('x'),
+        traitInteractions: Array(meta.counts.traitInteractions || 0).fill('x'),
         conflictResolution: Array(meta.counts.conflictResolution).fill('x'),
         evidence: Array(meta.counts.evidence).fill('x'),
         applicationNotes: Array(meta.counts.applicationNotes).fill('x')
@@ -168,6 +182,14 @@ function validateGenomeMeta(input) {
   }
   if (!meta.createdAt) errors.push('createdAt is required');
   if (!meta.updatedAt) errors.push('updatedAt is required');
+  if (hasOwn(input, 'dependencies') && input.dependencies !== null && typeof input.dependencies === 'object') {
+    if ('skills' in input.dependencies && !Array.isArray(input.dependencies.skills)) {
+      errors.push('dependencies.skills must be an array of strings');
+    }
+    if ('genomes' in input.dependencies && !Array.isArray(input.dependencies.genomes)) {
+      errors.push('dependencies.genomes must be an array of strings');
+    }
+  }
   validatePersonaV3Requirements(
     {
       version: meta.version,
@@ -183,7 +205,8 @@ function validateGenomeMeta(input) {
     {
       cognitiveProfile: Array(meta.counts.cognitiveProfile).fill('x'),
       communicationStyle: Array(meta.counts.communicationStyle).fill('x'),
-      biases: Array(meta.counts.biases).fill('x')
+      biases: Array(meta.counts.biases).fill('x'),
+      traitInteractions: Array(meta.counts.traitInteractions || 0).fill('x')
     },
     errors
   );