@jaimevalasek/aioson 1.7.0 → 1.8.0

package/src/commands/gate-approve.js

@@ -0,0 +1,198 @@
+'use strict';
+
+/**
+ * aioson gate:approve — approve a phase gate for a feature.
+ *
+ * Validates with gate:check before writing. If gate:check fails, blocks approval.
+ * Writes flat frontmatter fields to spec-{slug}.md:
+ *   gate_requirements, gate_design, gate_plan, gate_execution
+ *
+ * Usage:
+ *   aioson gate:approve . --feature=checkout --gate=C
+ *   aioson gate:approve . --feature=checkout --gate=C --json
+ *
+ * If gate:check fails, shows exact manual fallback: file, field, and value to set.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const {
+  contextDir,
+  readFileSafe,
+  fileExists,
+  parseFrontmatter,
+  parseGatesFromSpec,
+  GATE_NAMES,
+  GATE_ALIASES
+} = require('../preflight-engine');
+const { runGateCheck } = require('./gate-check');
+
+const BAR = '━'.repeat(45);
+
+const GATE_FLAT_FIELDS = {
+  A: 'gate_requirements',
+  B: 'gate_design',
+  C: 'gate_plan',
+  D: 'gate_execution'
+};
+
+const GATE_NEXT_AGENTS = {
+  A: { agent: '@architect', action: '/architect', why: 'Gate A (requirements) approved — architecture can proceed' },
+  B: { agent: '@pm', action: '/pm', why: 'Gate B (design) approved — implementation plan can be written' },
+  C: { agent: '@orchestrator or @dev', action: '/orchestrator (MEDIUM) or /dev (MICRO/SMALL)', why: 'Gate C (plan) approved — implementation can proceed' },
+  D: { agent: 'feature complete', action: 'mark feature done in features.md', why: 'Gate D (execution) approved — feature is complete' }
+};
+
+/**
+ * Update or insert a flat frontmatter field in a markdown file.
+ * Preserves all other frontmatter fields. Uses flat key: value format.
+ */
+function updateFrontmatterField(content, field, value) {
+  const fmMatch = content.match(/^(---\r?\n)([\s\S]*?)(\r?\n---)/);
+  if (!fmMatch) {
+    // No frontmatter — prepend it
+    return `---\n${field}: ${value}\n---\n\n${content}`;
+  }
+
+  const prefix = fmMatch[1];
+  const fmBody = fmMatch[2];
+  const suffix = fmMatch[3];
+  const rest = content.slice(fmMatch[0].length);
+
+  const lines = fmBody.split(/\r?\n/);
+  let found = false;
+  const updated = lines.map((line) => {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) return line;
+    const key = line.slice(0, colonIdx).trim();
+    if (key === field) {
+      found = true;
+      return `${field}: ${value}`;
+    }
+    return line;
+  });
+
+  if (!found) updated.push(`${field}: ${value}`);
+
+  return `${prefix}${updated.join('\n')}${suffix}${rest}`;
+}
+
+async function runGateApprove({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const slug = options.feature ? String(options.feature) : null;
+  let gateLetter = options.gate ? String(options.gate).toUpperCase() : null;
+
+  if (!slug) {
+    if (options.json) return { ok: false, reason: 'missing_feature' };
+    logger.log('--feature=<slug> is required.');
+    return { ok: false };
+  }
+
+  if (!gateLetter) {
+    if (options.json) return { ok: false, reason: 'missing_gate' };
+    logger.log('--gate=<A|B|C|D> is required.');
+    return { ok: false };
+  }
+
+  // Resolve aliases
+  if (GATE_ALIASES[gateLetter.toLowerCase()]) {
+    gateLetter = GATE_ALIASES[gateLetter.toLowerCase()];
+  }
+
+  if (!GATE_NAMES[gateLetter]) {
+    if (options.json) return { ok: false, reason: 'invalid_gate', gate: gateLetter };
+    logger.log(`Invalid gate: ${gateLetter}. Use A, B, C, or D.`);
+    return { ok: false };
+  }
+
+  // Step 1: run gate:check first (AC-SDLC-06 — gate:approve fails if gate:check fails)
+  const silentLogger = { log: () => {} };
+  const check = await runGateCheck({
+    args: [targetDir],
+    options: { feature: slug, gate: gateLetter, json: true },
+    logger: silentLogger
+  });
+
+  const specFile = path.join(contextDir(targetDir), `spec-${slug}.md`);
+  const specExists = await fileExists(specFile);
+  const specFieldName = GATE_FLAT_FIELDS[gateLetter];
+  const gateName = GATE_NAMES[gateLetter];
+
+  if (!check.ok) {
+    // Gate check failed — block approval and show manual fallback (AC-SDLC-08)
+    const result = {
+      ok: false,
+      blocked: true,
+      gate: gateLetter,
+      gate_name: gateName,
+      feature: slug,
+      reason: 'gate_check_failed',
+      missing: check.missing || [],
+      manual_fallback: specExists
+        ? `To manually approve when prerequisites are met:\n  File: .aioson/context/spec-${slug}.md\n  Field: ${specFieldName}\n  Value: approved`
+        : `spec-${slug}.md does not exist. Create it with ${specFieldName}: approved in frontmatter after prerequisites are satisfied.`
+    };
+
+    if (options.json) return result;
+
+    logger.log('');
+    logger.log(`Gate ${gateLetter} (${gateName}) — ${slug}`);
+    logger.log(BAR);
+    logger.log(`Result: ✗ BLOCKED — gate:check did not pass`);
+    logger.log('');
+    logger.log('Missing prerequisites:');
+    for (const m of check.missing || []) logger.log(`  ✗ ${m}`);
+    logger.log('');
+    logger.log('Manual fallback (use only after all prerequisites are satisfied):');
+    logger.log(`  File:  .aioson/context/spec-${slug}.md`);
+    logger.log(`  Field: ${specFieldName}`);
+    logger.log(`  Value: approved`);
+    logger.log('');
+    logger.log('Tip: re-run gate:check after satisfying prerequisites, then gate:approve again.');
+    logger.log('');
+    return result;
+  }
+
+  // Step 2: write flat frontmatter field (AC-SDLC-07 — flat format, not nested phase_gates)
+  let content = specExists ? await readFileSafe(specFile) : null;
+
+  if (!content) {
+    // Create minimal spec with gate field
+    content = `---\nfeature: ${slug}\n${specFieldName}: approved\n---\n\n# Spec — ${slug}\n\nCreated by gate:approve.\n`;
+  } else {
+    content = updateFrontmatterField(content, specFieldName, 'approved');
+  }
+
+  await fs.writeFile(specFile, content, 'utf8');
+
+  const nextInfo = GATE_NEXT_AGENTS[gateLetter];
+  const result = {
+    ok: true,
+    gate: gateLetter,
+    gate_name: gateName,
+    feature: slug,
+    field_written: specFieldName,
+    spec_file: `.aioson/context/spec-${slug}.md`,
+    next_agent: nextInfo.agent,
+    next_action: nextInfo.action,
+    why: nextInfo.why
+  };
+
+  if (options.json) return result;
+
+  logger.log('');
+  logger.log(`Gate ${gateLetter} (${gateName}) — ${slug}`);
+  logger.log(BAR);
+  logger.log(`Result: ✓ APPROVED`);
+  logger.log('');
+  logger.log(`Written: ${specFieldName}: approved → .aioson/context/spec-${slug}.md`);
+  logger.log('');
+  logger.log(`Next agent: ${nextInfo.agent}`);
+  logger.log(`Why: ${nextInfo.why}`);
+  logger.log(`Action: ${nextInfo.action}`);
+  logger.log('');
+
+  return result;
+}
+
+module.exports = { runGateApprove };

package/src/commands/gate-check.js

@@ -19,6 +19,7 @@ const {
   fileExists,
   parseGatesFromSpec,
   parseFrontmatter,
+  detectClassification,
   GATE_NAMES,
   GATE_ALIASES
 } = require('../preflight-engine');
@@ -52,6 +53,7 @@ async function checkGate(targetDir, slug, gateLetter) {
   const specContent = await readFileSafe(specFile);
   const gates = specContent ? parseGatesFromSpec(specContent) : {};
   const fm = specContent ? parseFrontmatter(specContent) : {};
+  const classification = await detectClassification(targetDir, slug);
 
   const gateName = GATE_NAMES[gateLetter];
   const gateStatus = gates[gateName] || 'pending';
@@ -79,12 +81,19 @@ async function checkGate(targetDir, slug, gateLetter) {
     const exists = await fileExists(filePath);
     if (exists) {
       let detail = null;
+      let ok = true;
       const content = await readFileSafe(filePath);
       if (content) {
         const fileFm = parseFrontmatter(content);
-        if (fileFm.status) detail = `status: ${fileFm.status}`;
+        const status = fileFm.status ? String(fileFm.status).toLowerCase() : null;
+        if (status) detail = `status: ${status}`;
+
+        if (gateLetter === 'C' && status !== 'approved') {
+          ok = false;
+          missing.push(`${fileName} status is ${status || 'missing'} — @pm must approve the implementation plan`);
+        }
       }
-      evidence.push({ type: 'artifact', file: fileName, exists: true, detail, ok: true });
+      evidence.push({ type: 'artifact', file: fileName, exists: true, detail, ok });
     } else {
       evidence.push({ type: 'artifact', file: fileName, exists: false, ok: false });
       missing.push(`${fileName} not found`);
@@ -130,11 +139,21 @@ async function checkGate(targetDir, slug, gateLetter) {
 
   let recommendation = '';
   if (result === 'PASS') {
-    const nextAgents = { A: '@architect', B: '@dev or @pm', C: '@dev', D: 'feature complete' };
+    const nextAgents = {
+      A: '@architect',
+      B: classification === 'MEDIUM' ? '@pm' : '@dev',
+      C: classification === 'MEDIUM' ? '@orchestrator' : '@dev',
+      D: 'feature complete'
+    };
     recommendation = `${nextAgents[gateLetter] || 'proceed'} can proceed`;
   } else {
-    const fixAgents = { A: 'complete requirements (@analyst)', B: 'complete design (@architect)', C: 'approve implementation plan', D: 'complete implementation and run @qa' };
-    recommendation = `BLOCKED — ${fixAgents[gateLetter] || 'resolve missing items'} first`;
+    const fixAgents = {
+      A: `activate @analyst to produce requirements-${slug}.md, then run: aioson gate:approve . --feature=${slug} --gate=A`,
+      B: `activate @architect to produce architecture.md, then run: aioson gate:approve . --feature=${slug} --gate=B`,
+      C: `activate @pm to produce and approve implementation-plan-${slug}.md, then run: aioson gate:approve . --feature=${slug} --gate=C`,
+      D: `activate @qa for final verification; if QA passes, run: aioson gate:approve . --feature=${slug} --gate=D`
+    };
+    recommendation = `BLOCKED — ${fixAgents[gateLetter] || 'resolve missing items'}`;
   }
 
   return {

package/src/commands/genome-doctor.js

@@ -4,6 +4,84 @@ const fs = require('node:fs/promises');
 const path = require('node:path');
 const { loadCompatibleGenome } = require('../lib/genomes/compat');
 
+const INSTALLED_SKILLS_DIR = '.aioson/installed-skills';
+const BUILTIN_SKILLS_DIR = '.aioson/skills';
+const GENOMES_DIR = '.aioson/genomes';
+
+/**
+ * Walk up the directory tree from startDir looking for a dir that contains .aioson/.
+ * Falls back to process.cwd() if not found.
+ */
+async function findProjectRoot(startDir) {
+  let current = startDir;
+  for (let i = 0; i < 10; i++) {
+    try {
+      await fs.access(path.join(current, '.aioson'));
+      return current;
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+  return process.cwd();
+}
+
+/**
+ * Check whether a skill slug is available in the project.
+ * Checks installed skills AND built-in skills directories.
+ */
+async function isSkillAvailable(projectRoot, slug) {
+  const installedPath = path.join(projectRoot, INSTALLED_SKILLS_DIR, slug, 'SKILL.md');
+  const builtinExact = path.join(projectRoot, BUILTIN_SKILLS_DIR, slug, 'SKILL.md');
+  // Also check as a flat dir (some skills live directly under .aioson/skills/{slug}/)
+  const builtinDir = path.join(projectRoot, BUILTIN_SKILLS_DIR, slug);
+
+  for (const candidate of [installedPath, builtinExact]) {
+    try {
+      await fs.access(candidate);
+      return { found: true, path: path.relative(projectRoot, path.dirname(candidate)) };
+    } catch { /* not found */ }
+  }
+
+  try {
+    const stat = await fs.stat(builtinDir);
+    if (stat.isDirectory()) {
+      return { found: true, path: path.relative(projectRoot, builtinDir) };
+    }
+  } catch { /* not found */ }
+
+  return { found: false };
+}
+
+/**
+ * Check whether a genome slug is available in the project.
+ */
+async function isGenomeAvailable(projectRoot, slug) {
+  const genomePath = path.join(projectRoot, GENOMES_DIR, `${slug}.md`);
+  try {
+    await fs.access(genomePath);
+    return { found: true, path: path.relative(projectRoot, genomePath) };
+  } catch {
+    return { found: false };
+  }
+}
+
+/**
+ * Read and parse the .meta.json companion file for a genome .md.
+ * Returns null if absent or invalid JSON.
+ */
+async function readGenomeMeta(mdFilePath) {
+  const slug = path.basename(mdFilePath, '.md');
+  const metaPath = path.join(path.dirname(mdFilePath), `${slug}.meta.json`);
+  try {
+    const raw = await fs.readFile(metaPath, 'utf8');
+    return { meta: JSON.parse(raw), metaPath };
+  } catch {
+    return { meta: null, metaPath };
+  }
+}
+
 async function runGenomeDoctor({ args, options = {}, logger }) {
   const target = args[0];
   if (!target) {
@@ -13,6 +91,7 @@ async function runGenomeDoctor({ args, options = {}, logger }) {
   const filePath = path.resolve(process.cwd(), target);
   const raw = await fs.readFile(filePath, 'utf8');
   const loaded = loadCompatibleGenome(raw, { filePath });
+
   const result = {
     ok: true,
     file: filePath,
@@ -21,18 +100,96 @@ async function runGenomeDoctor({ args, options = {}, logger }) {
     slug: loaded.document.slug,
     type: loaded.document.type,
     depth: loaded.document.depth,
-    evidenceMode: loaded.document.evidenceMode
+    evidenceMode: loaded.document.evidenceMode,
+    dependencies: {
+      skills: [],
+      genomes: [],
+      missing: { skills: [], genomes: [] }
+    }
   };
 
-  if (options.json) return result;
+  // Check for .meta.json companion
+  const { meta, metaPath } = await readGenomeMeta(filePath);
+  const hasMeta = Boolean(meta);
+  result.hasMeta = hasMeta;
+
+  if (!options.json) {
+    logger.log(`Genome file: ${filePath}`);
+    logger.log(`Format: ${result.detectedFormat}`);
+    logger.log(`Migrated internally: ${result.migrated ? 'yes' : 'no'}`);
+    logger.log(`Slug: ${result.slug}`);
+    logger.log(`Type: ${result.type}`);
+    logger.log(`Depth: ${result.depth}`);
+    logger.log(`Evidence mode: ${result.evidenceMode}`);
+    logger.log(`Meta file: ${hasMeta ? path.relative(process.cwd(), metaPath) : 'not found'}`);
+  }
+
+  // Dependency check — requires meta.json with dependencies field
+  const deps = hasMeta && meta.dependencies
+    ? {
+        skills: Array.isArray(meta.dependencies.skills) ? meta.dependencies.skills : [],
+        genomes: Array.isArray(meta.dependencies.genomes) ? meta.dependencies.genomes : []
+      }
+    : { skills: [], genomes: [] };
+
+  result.dependencies.skills = deps.skills;
+  result.dependencies.genomes = deps.genomes;
+
+  if (deps.skills.length === 0 && deps.genomes.length === 0) {
+    if (!options.json) logger.log('\nDependencies: none declared');
+    return result;
+  }
+
+  const projectRoot = await findProjectRoot(path.dirname(filePath));
+  const missingSkills = [];
+  const missingGenomes = [];
+
+  if (!options.json) logger.log('\nChecking dependencies...');
+
+  for (const slug of deps.skills) {
+    const check = await isSkillAvailable(projectRoot, slug);
+    if (check.found) {
+      if (!options.json) logger.log(`  skill "${slug}": OK (${check.path})`);
+    } else {
+      missingSkills.push(slug);
+      if (!options.json) logger.log(`  skill "${slug}": MISSING`);
+    }
+  }
+
+  for (const slug of deps.genomes) {
+    const check = await isGenomeAvailable(projectRoot, slug);
+    if (check.found) {
+      if (!options.json) logger.log(`  genome "${slug}": OK (${check.path})`);
+    } else {
+      missingGenomes.push(slug);
+      if (!options.json) logger.log(`  genome "${slug}": MISSING`);
+    }
+  }
+
+  result.dependencies.missing = { skills: missingSkills, genomes: missingGenomes };
+
+  const hasMissing = missingSkills.length > 0 || missingGenomes.length > 0;
+  if (hasMissing) {
+    result.ok = false;
+    if (!options.json) {
+      logger.log('\nMissing dependencies detected.');
+      if (missingSkills.length > 0) {
+        logger.log('Install missing skills:');
+        for (const slug of missingSkills) {
+          logger.log(`  aioson skill:install --slug=${slug}`);
+        }
+      }
+      if (missingGenomes.length > 0) {
+        logger.log('Install missing genomes:');
+        for (const slug of missingGenomes) {
+          logger.log(`  aioson genome:install --slug=${slug}`);
+        }
+      }
+    }
+  } else if (!options.json) {
+    logger.log('\nAll dependencies satisfied.');
+  }
 
-  logger.log(`Genome file: ${filePath}`);
-  logger.log(`Format: ${result.detectedFormat}`);
-  logger.log(`Migrated internally: ${result.migrated ? 'yes' : 'no'}`);
-  logger.log(`Slug: ${result.slug}`);
-  logger.log(`Type: ${result.type}`);
-  logger.log(`Depth: ${result.depth}`);
-  logger.log(`Evidence mode: ${result.evidenceMode}`);
   return result;
 }
 

package/src/commands/git-guard.js

@@ -0,0 +1,170 @@
+'use strict';
+
+/**
+ * aioson git:guard — inspect staged files before commit
+ *
+ * Usage:
+ *   aioson git:guard .
+ *   aioson git:guard . --json
+ *   aioson git:guard . --allow-warnings --json
+ *   aioson git:guard . --install-hook
+ *   aioson git:guard . --uninstall-hook
+ */
+
+const path = require('node:path');
+const {
+  inspectStagedChanges,
+  installPreCommitHook,
+  uninstallPreCommitHook
+} = require('../lib/git-commit-guard');
+
+function formatFinding(prefix, finding) {
+  const line = finding.line ? `:${finding.line}` : '';
+  return `${prefix} ${finding.path}${line} — ${finding.reason} [${finding.id}]`;
+}
+
+async function runGitGuard({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const allowWarnings = Boolean(options['allow-warnings'] || options.allowWarnings);
+  const installHook = Boolean(options['install-hook'] || options.installHook);
+  const uninstallHook = Boolean(options['uninstall-hook'] || options.uninstallHook || options['remove-hook'] || options.removeHook);
+
+  if (installHook && uninstallHook) {
+    process.exitCode = 1;
+    const failure = {
+      ok: false,
+      error: 'git_guard_invalid_options',
+      message: 'Use either --install-hook or --uninstall-hook, not both.',
+      projectDir: targetDir
+    };
+    if (!options.json) logger.error(failure.message);
+    return failure;
+  }
+
+  if (installHook || uninstallHook) {
+    let hookResult;
+    try {
+      hookResult = installHook
+        ? await installPreCommitHook(targetDir, options)
+        : await uninstallPreCommitHook(targetDir, options);
+    } catch (error) {
+      process.exitCode = 1;
+      const failure = {
+        ok: false,
+        error: 'git_guard_hook_failed',
+        message: error.message,
+        projectDir: targetDir
+      };
+      if (!options.json) logger.error(`Commit hook operation failed: ${error.message}`);
+      return failure;
+    }
+
+    if (!hookResult.ok) process.exitCode = 1;
+    if (options.json) return hookResult;
+
+    logger.log('');
+    logger.log(`Commit hook — ${hookResult.gitRoot}`);
+    if (!hookResult.ok) {
+      logger.error(hookResult.message);
+      return hookResult;
+    }
+
+    if (installHook) {
+      logger.log(hookResult.dryRun ? 'Pre-commit hook dry-run complete.' : 'Pre-commit hook installed.');
+      logger.log(`Hook path: ${hookResult.hookPath}`);
+      if (hookResult.backedUpExistingHook) {
+        logger.log(`Existing hook backed up to: ${hookResult.backupPath}`);
+      }
+      if (hookResult.chainedBackupHook) {
+        logger.log('AIOSON will chain the backed-up hook after the guard passes.');
+      }
+      return hookResult;
+    }
+
+    if (hookResult.removed || hookResult.dryRun) {
+      logger.log(hookResult.dryRun ? 'Pre-commit hook uninstall dry-run complete.' : 'Pre-commit hook removed.');
+      if (hookResult.restoredBackup) {
+        logger.log(`Restored previous hook from: ${hookResult.backupPath}`);
+      }
+      return hookResult;
+    }
+
+    logger.log(hookResult.message);
+    return hookResult;
+  }
+
+  let result;
+  try {
+    result = await inspectStagedChanges(targetDir, {
+      allowWarnings,
+      config: options.config
+    });
+  } catch (error) {
+    process.exitCode = 1;
+    const failure = {
+      ok: false,
+      error: 'git_guard_failed',
+      message: error.message,
+      projectDir: targetDir
+    };
+    if (!options.json) logger.error(`Commit guard failed: ${error.message}`);
+    return failure;
+  }
+
+  const output = {
+    ok: result.ok,
+    projectDir: targetDir,
+    gitRoot: result.gitRoot,
+    strict: result.strict,
+    policy: result.policy,
+    stagedFiles: result.stagedFiles,
+    files: result.files,
+    errors: result.errors,
+    warnings: result.warnings,
+    suggestedCommands: result.suggestedCommands,
+    summary: result.summary
+  };
+
+  if (!result.ok) process.exitCode = 1;
+
+  if (options.json) return output;
+
+  logger.log('');
+  logger.log(`Commit guard — ${result.gitRoot}`);
+  logger.log(`Staged files: ${result.summary.stagedCount}`);
+  logger.log(`Policy: ${result.policy.loaded ? result.policy.path : 'default built-in policy (no project config found)'}`);
+
+  if (result.summary.stagedCount === 0) {
+    logger.error('No staged files found. Stage explicit files before committing.');
+    return output;
+  }
+
+  if (result.ok) {
+    logger.log('Commit guard passed.');
+    return output;
+  }
+
+  logger.error('Commit guard blocked this commit.');
+  if (result.errors.length > 0) {
+    logger.error('Errors:');
+    for (const finding of result.errors) {
+      logger.error(formatFinding('  [ERROR]', finding));
+    }
+  }
+  if (result.warnings.length > 0) {
+    logger.error('Warnings:');
+    for (const finding of result.warnings) {
+      logger.error(formatFinding('  [WARN] ', finding));
+    }
+  }
+  if (result.suggestedCommands.length > 0) {
+    logger.error('Suggested next commands:');
+    for (const command of result.suggestedCommands) {
+      logger.error(`  ${command}`);
+    }
+  }
+
+  return output;
+}
+
+module.exports = { runGitGuard };