gemstack-ai 1.2.0 → 1.4.0

package/specs/010-agent-swarm-visual-qa/visual-qa.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://gemstack.dev/schemas/v1/visual-qa.json",
+  "version": "1.0.0",
+  "feature_id": "010-agent-swarm-visual-qa",
+  "target_base_url": "http://localhost:3000",
+  "scenarios": [
+    {
+      "scenario_id": "VQA-LOGIN-001",
+      "description": "Login screen mobile portrait conformance",
+      "route": "/login",
+      "acceptance_ids": [
+        "TEST-VISUAL-A01"
+      ],
+      "viewport": {
+        "name": "mobile-portrait",
+        "width": 375,
+        "height": 667,
+        "device_scale_factor": 2,
+        "color_scheme": "light"
+      },
+      "selectors": {
+        "root": "#login-container",
+        "mask": [
+          ".dynamic-timestamp",
+          ".live-avatar"
+        ]
+      },
+      "tolerances": {
+        "max_diff_percentage": 0,
+        "anti_aliasing_threshold": 0.1
+      },
+      "baseline": {
+        "image_path": "specs/010-agent-swarm-visual-qa/baselines/vqa-login-001.png",
+        "image_sha256": "c35ba1ccd49a5e52bdc206d7e8723bc31d288d4f38b6c9045f4f78ab79e6018f",
+        "dom_hash": "c5d6e7f80123456789abcdef0123456789abcdef0123456789abcdef01234567",
+        "approved_by": "human-lead",
+        "approved_at": "2026-09-11T19:10:00Z"
+      }
+    }
+  ]
+}

package/src/cli.js

@@ -11,6 +11,9 @@ const installCommand = require('./commands/install');
 const verifyCommand = require('./commands/verify');
 const collectCommand = require('./commands/collect');
 const shipCommand = require('./commands/ship');
+const contextCommand = require('./commands/context');
+const swarmCommand = require('./commands/swarm');
+const visualCommand = require('./commands/visual');
 
 async function main() {
     const { command, args, flags } = parser.parse(process.argv);
@@ -24,6 +27,9 @@ Commands:
   verify    Run complete integrity, state, memory and security audit (alias: audit)
   collect   Collect mechanical test matrix and closure evidence
   ship      Verify closure gates and transition feature to shipped
+  context   Generate, show, or verify context capsule
+  swarm     Plan or validate agent swarm work and write partitions
+  vqa       Validate or promote visual QA manifests and evidence
   list      List available skills
   show      Show content of a skill
   handoff   Show content of handoff.md
@@ -48,6 +54,10 @@ Options:
             case 'audit': await verifyCommand(flags); break;
             case 'collect': await collectCommand(flags); break;
             case 'ship': await shipCommand(flags); break;
+            case 'context': await contextCommand(args, flags); break;
+            case 'swarm': await swarmCommand(args, flags); break;
+            case 'vqa':
+            case 'visual': await visualCommand(args, flags); break;
             case 'list': await listCommand(flags); break;
             case 'show': await showCommand(args[0], flags); break;
             case 'hooks': hooksCommand.installHooks(flags.target); break;

package/src/commands/context.js

@@ -0,0 +1,95 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const logger = require('../lib/logger');
+const fssafe = require('../lib/filesystem-safe');
+const {
+  generateContextCapsule,
+  validateContextCapsule
+} = require('../lib/context-capsule');
+
+async function contextCommand(args = [], flags = {}) {
+  const subcommand = args[0] || 'show';
+  const targetDir = flags.target ? path.resolve(flags.target) : process.cwd();
+
+  let activeSpec = (args[1] && !args[1].startsWith('-') ? args[1] : null) || flags.feature;
+  if (!activeSpec) {
+    const stateFile = path.join(targetDir, '.gemstack/state.json');
+    if (fs.existsSync(stateFile)) {
+      try {
+        const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+        activeSpec = state.active_spec;
+      } catch (_) {}
+    }
+  }
+
+  if (!activeSpec) {
+    // Check if specs/009-context-capsule or specs/current exists
+    if (fs.existsSync(path.join(targetDir, 'specs/009-context-capsule'))) {
+      activeSpec = 'specs/009-context-capsule';
+    } else if (fs.existsSync(path.join(targetDir, 'specs/current'))) {
+      activeSpec = 'specs/current';
+    } else {
+      logger.error('No active feature found or specified via --feature.');
+      process.exit(1);
+    }
+  }
+
+  switch (subcommand) {
+    case 'generate': {
+      logger.info(`Generating context capsule for "${activeSpec}" in: ${targetDir}`);
+      try {
+        const res = generateContextCapsule(targetDir, activeSpec);
+        logger.ok(`Context capsule generated successfully: ${res.path} (${res.byteLength} bytes, ${res.invariantsCount} invariants).`);
+      } catch (err) {
+        logger.error(`Generation failed: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'show': {
+      const capsuleFile = path.join(targetDir, activeSpec, 'context-capsule.json');
+      if (!fs.existsSync(capsuleFile)) {
+        logger.error(`Context capsule not found at: ${capsuleFile}`);
+        process.exit(1);
+      }
+      const raw = fs.readFileSync(capsuleFile, 'utf8');
+      if (flags.json) {
+        console.log(raw);
+      } else {
+        const parsed = JSON.parse(raw);
+        console.log('=== Gemstack Context Capsule ===');
+        console.log(`Schema Version: ${parsed.schema_version}`);
+        console.log(`Project:        ${parsed.project ? parsed.project.name : 'unknown'}`);
+        console.log(`Feature:        ${parsed.project ? parsed.project.active_feature : 'unknown'}`);
+        console.log(`Lifecycle:      ${parsed.project ? parsed.project.lifecycle_status : 'unknown'}`);
+        console.log(`Sources:        ${parsed.provenance ? parsed.provenance.sources.length : 0} files`);
+        console.log(`Invariants:     ${parsed.canonical_invariants ? parsed.canonical_invariants.length : 0} rules`);
+        console.log(`Contracts:      ${parsed.frozen_contracts ? parsed.frozen_contracts.length : 0} contracts`);
+        console.log(`Acceptance:     ${parsed.acceptance_matrix ? parsed.acceptance_matrix.total_required : 0} tests`);
+      }
+      break;
+    }
+
+    case 'verify': {
+      logger.info(`Auditing context capsule for "${activeSpec}" in: ${targetDir}`);
+      const res = validateContextCapsule(targetDir, activeSpec);
+      if (res.valid) {
+        logger.ok(`[OK] Context capsule is VALID and FRESH for ${activeSpec}.`);
+      } else {
+        logger.error(`[${res.state}] Context capsule validation failed.`);
+        for (const f of res.findings) {
+          logger.error(` - [${f.code}] ${f.message}`);
+        }
+        process.exit(1);
+      }
+      break;
+    }
+
+    default:
+      logger.error(`Unknown context subcommand: ${subcommand}. Valid subcommands: generate, show, verify.`);
+      process.exit(1);
+  }
+}
+
+module.exports = contextCommand;

package/src/commands/swarm.js

@@ -0,0 +1,111 @@
+/**
+ * Gemstack Swarm Command Handler (Upgrade E)
+ *
+ * Implements "gemstack swarm plan" and "gemstack swarm validate" subcommands.
+ * Read-only planning and manifest auditing.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const logger = require('../lib/logger');
+const fssafe = require('../lib/filesystem-safe');
+const { readState } = require('../lib/state');
+const { planSwarmWaves, validateSwarmManifest, canonicalSerialize } = require('../lib/swarm');
+
+async function swarmCommand(args = [], flags = {}) {
+  const subcommand = args[0] || 'validate';
+  const targetDir = flags.target ? path.resolve(flags.target) : process.cwd();
+
+  let state;
+  try {
+    state = readState(targetDir);
+  } catch (e) {
+    logger.error(`Error loading .gemstack/state.json: ${e.message}`);
+    process.exit(1);
+  }
+
+  const activeSpec = state.active_spec;
+  if (!activeSpec) {
+    if (flags.json) {
+      console.log(JSON.stringify({ status: 'NO_ACTIVE_SPEC', message: 'No active feature spec set.' }));
+    } else {
+      logger.info('Sin spec activa pendiente. Opera en modo legacy.');
+    }
+    return;
+  }
+
+  const featureDir = fssafe.resolveSafe(targetDir, activeSpec);
+
+  if (subcommand === 'plan') {
+    const tasksPath = path.join(featureDir, 'tasks.md');
+    if (!fs.existsSync(tasksPath)) {
+      logger.error(`tasks.md not found in "${activeSpec}".`);
+      process.exit(1);
+    }
+
+    const tasksRaw = fs.readFileSync(tasksPath, 'utf8');
+    // Extract tasks with parallel tag or lines
+    const parsedTasks = [];
+    const lines = tasksRaw.split('\n');
+    for (const line of lines) {
+      const m = line.match(/###\s+(?:Task\s+)?([A-Za-z0-9_-]+)/i);
+      if (m) {
+        parsedTasks.push({
+          task_id: m[1],
+          description: line.replace(/^#+\s*/, '').trim(),
+          assigned_role: 'implementer',
+          worker_id: `worker-impl-${parsedTasks.length + 1}`,
+          write_set: [`src/${m[1].toLowerCase()}.js`],
+          status: 'PLANNED'
+        });
+      }
+    }
+
+    const waves = planSwarmWaves(parsedTasks);
+    const manifest = {
+      $schema: 'https://gemstack.dev/schemas/v1/swarm.json',
+      version: '1.0.0',
+      feature_id: activeSpec,
+      source_capsule_hash: 'd0mmy_c4psul3_h4sh',
+      max_workers: 4,
+      waves
+    };
+
+    const manifestPath = path.join(featureDir, 'swarm.json');
+    if (!flags['dry-run']) {
+      fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+      logger.ok(`Swarm plan generated: ${manifestPath} (${waves.length} wave(s)).`);
+    } else {
+      logger.info(`[DRY-RUN] Swarm plan computed: ${waves.length} wave(s).`);
+    }
+
+    if (flags.json) {
+      console.log(JSON.stringify(manifest, null, 2));
+    }
+  } else if (subcommand === 'validate') {
+    const res = validateSwarmManifest(targetDir, activeSpec);
+    if (flags.json) {
+      console.log(JSON.stringify(res, null, 2));
+      return;
+    }
+
+    if (res.state === 'MISSING') {
+      logger.info(`[LEGACY] No se detectó swarm.json en "${activeSpec}".`);
+      return;
+    }
+
+    if (res.valid) {
+      logger.ok(`Swarm manifest validado con éxito: ${activeSpec}/swarm.json.`);
+    } else {
+      for (const f of res.findings) {
+        logger.error(`[${f.code}] ${f.details}`);
+      }
+      process.exit(1);
+    }
+  } else {
+    logger.error(`Unknown swarm subcommand: "${subcommand}". Use "plan" or "validate".`);
+    process.exit(1);
+  }
+}
+
+module.exports = swarmCommand;

package/src/commands/verify.js

@@ -376,6 +376,98 @@ module.exports = async (flags) => {
         logger.ok('Sin spec activa configurada para validación de evidencia de cierre.');
     }
 
+    // 5.1 Verificación de Políticas de Costos y Proveedores (Upgrade C - Read-Only)
+    const { loadCostLedger } = require('../lib/cost-ledger');
+    let costLedgerFound = false;
+    const ledgerCandidates = [];
+    if (loadedState && loadedState.active_spec) {
+        ledgerCandidates.push(fssafe.resolveSafe(targetDir, path.join(loadedState.active_spec, 'cost-ledger.json')));
+    }
+    ledgerCandidates.push(fssafe.resolveSafe(targetDir, 'cost-ledger.json'));
+    ledgerCandidates.push(fssafe.resolveSafe(targetDir, '.gemstack/cost-ledger.json'));
+
+    for (const lPath of ledgerCandidates) {
+        if (fs.existsSync(lPath)) {
+            costLedgerFound = true;
+            const res = loadCostLedger(lPath);
+            if (res.findings.length > 0) {
+                for (const f of res.findings) {
+                    if (f.is_blocking) {
+                        logger.error(`[COST_SAFETY_BLOCKER] ${f.code}: ${f.details}`);
+                        totalErrors++;
+                    } else {
+                        logger.warn(`[COST_SAFETY_WARNING] ${f.code}: ${f.details}`);
+                        totalWarnings++;
+                    }
+                }
+            } else {
+                logger.ok(`Cost ledger verificado (${path.basename(lPath)}): íntegro y sin secretos.`);
+            }
+            break;
+        }
+    }
+
+    if (!costLedgerFound) {
+        logger.info('[LEGACY] [LEGACY_NO_PROVIDERS_DECLARED] No se detectaron declaraciones de costos o proveedores (Modo Legacy Provider-Free).');
+    }
+
+    // 5.2 Verificación de Context Capsule (Upgrade D - Read-Only)
+    logger.info('--- 5.2 Verificación de Context Capsule (Read-Only) ---');
+    if (loadedState && loadedState.active_spec) {
+        const { validateContextCapsule } = require('../lib/context-capsule');
+        const capResult = validateContextCapsule(targetDir, loadedState.active_spec);
+        if (capResult.valid) {
+            logger.ok(`Context capsule verificado y fresco (${loadedState.active_spec}/context-capsule.json).`);
+        } else if (capResult.state === 'MISSING') {
+            logger.info(`[LEGACY] No se detectó context-capsule.json en "${loadedState.active_spec}" (Modo Legacy Context-Free).`);
+        } else {
+            for (const f of capResult.findings) {
+                logger.error(`[${f.code}] ${f.message}`);
+                totalErrors++;
+            }
+        }
+    } else {
+        logger.ok('Sin spec activa configurada para verificación de context capsule.');
+    }
+
+    // 5.3 Verificación de Swarm Manifest (Upgrade E - Read-Only)
+    logger.info('--- 5.3 Verificación de Swarm Manifest & Partition Safety (Read-Only) ---');
+    if (loadedState && loadedState.active_spec) {
+        const { validateSwarmManifest } = require('../lib/swarm');
+        const swarmResult = validateSwarmManifest(targetDir, loadedState.active_spec);
+        if (swarmResult.valid) {
+            logger.ok(`Swarm manifest verificado y sin colisiones (${loadedState.active_spec}/swarm.json).`);
+        } else if (swarmResult.state === 'MISSING') {
+            logger.info(`[LEGACY] No se detectó swarm.json en "${loadedState.active_spec}" (Modo Legacy Swarm-Free).`);
+        } else {
+            for (const f of swarmResult.findings) {
+                logger.error(`[${f.code}] ${f.details || f.message}`);
+                totalErrors++;
+            }
+        }
+    } else {
+        logger.ok('Sin spec activa configurada para verificación de swarm manifest.');
+    }
+
+    // 5.4 Verificación de Visual QA Manifest & Baselines (Upgrade E - Read-Only)
+    logger.info('--- 5.4 Verificación de Visual QA Manifest & Baselines (Read-Only) ---');
+    if (loadedState && loadedState.active_spec) {
+        const { validateVisualManifest } = require('../lib/visual-qa');
+        const vqaResult = validateVisualManifest(targetDir, loadedState.active_spec);
+        if (vqaResult.valid) {
+            logger.ok(`Visual QA manifest y baselines íntegros (${loadedState.active_spec}/visual-qa.json).`);
+        } else if (vqaResult.state === 'MISSING') {
+            logger.info(`[LEGACY] No se detectó visual-qa.json en "${loadedState.active_spec}" (Modo Legacy Visual-Free).`);
+        } else {
+            for (const f of vqaResult.findings) {
+                logger.error(`[${f.code}] ${f.details || f.message}`);
+                totalErrors++;
+            }
+        }
+    } else {
+        logger.ok('Sin spec activa configurada para verificación de visual QA.');
+    }
+
     // 6. Seguridad Local y Anti-Silent Failures en Tests
     logger.info('--- 6/6 Verificación de Seguridad y Test Runners ---');
     const envPath = fssafe.resolveSafe(targetDir, '.env');

package/src/commands/visual.js

@@ -0,0 +1,82 @@
+/**
+ * Gemstack Visual QA Command Handler (Upgrade E)
+ *
+ * Implements "gemstack vqa validate" and "gemstack vqa promote" subcommands.
+ * Read-only validation and explicit baseline promotion.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const logger = require('../lib/logger');
+const fssafe = require('../lib/filesystem-safe');
+const { readState } = require('../lib/state');
+const { validateVisualManifest, promoteVisualBaseline } = require('../lib/visual-qa');
+
+async function visualCommand(args = [], flags = {}) {
+  const subcommand = args[0] || 'validate';
+  const targetDir = flags.target ? path.resolve(flags.target) : process.cwd();
+
+  let state;
+  try {
+    state = readState(targetDir);
+  } catch (e) {
+    logger.error(`Error loading .gemstack/state.json: ${e.message}`);
+    process.exit(1);
+  }
+
+  const activeSpec = state.active_spec;
+  if (!activeSpec) {
+    if (flags.json) {
+      console.log(JSON.stringify({ status: 'NO_ACTIVE_SPEC', message: 'No active feature spec set.' }));
+    } else {
+      logger.info('Sin spec activa pendiente. Opera en modo legacy.');
+    }
+    return;
+  }
+
+  if (subcommand === 'validate') {
+    const res = validateVisualManifest(targetDir, activeSpec);
+    if (flags.json) {
+      console.log(JSON.stringify(res, null, 2));
+      return;
+    }
+
+    if (res.state === 'MISSING') {
+      logger.info(`[LEGACY] No se detectó visual-qa.json en "${activeSpec}".`);
+      return;
+    }
+
+    if (res.valid) {
+      logger.ok(`Visual QA manifest validado con éxito: ${activeSpec}/visual-qa.json.`);
+    } else {
+      for (const f of res.findings) {
+        logger.error(`[${f.code}] ${f.details}`);
+      }
+      process.exit(1);
+    }
+  } else if (subcommand === 'promote') {
+    const scenarioId = args[1];
+    const liveImagePath = args[2];
+
+    if (!scenarioId || !liveImagePath) {
+      logger.error('Usage: gemstack vqa promote <scenario-id> <live-image-path>');
+      process.exit(1);
+    }
+
+    try {
+      const res = promoteVisualBaseline(targetDir, activeSpec, scenarioId, liveImagePath);
+      logger.ok(`Baseline promoted for scenario "${scenarioId}". Updated ${activeSpec}/visual-qa.json.`);
+      if (flags.json) {
+        console.log(JSON.stringify(res, null, 2));
+      }
+    } catch (err) {
+      logger.error(`Failed to promote baseline: ${err.message}`);
+      process.exit(1);
+    }
+  } else {
+    logger.error(`Unknown visual subcommand: "${subcommand}". Use "validate" or "promote".`);
+    process.exit(1);
+  }
+}
+
+module.exports = visualCommand;

package/src/lib/closure-context.js

@@ -220,7 +220,7 @@ function parseTaskMetadata(tasksContent) {
   const lines = normalized.split('\n');
   const tasks = [];
 
-  const taskHeaderRegex = /^[*-]\s+\[[ xX]\]\s+\*\*(T\d+):\s*(.*?)\*\*/;
+  const taskHeaderRegex = /^[*-]\s+\[[ xX]\]\s+\*\*([A-Za-z0-9_-]+):\s*(.*?)\*\*/;
   let currentTask = null;
 
   for (const line of lines) {
@@ -334,6 +334,23 @@ function resolveRelevantFiles(rootPath, featureDir, planBindings, taskList, plan
   if (fs.existsSync(path.join(rootPath, planPath))) filesSet.add(planPath);
   if (fs.existsSync(path.join(rootPath, tasksPath))) filesSet.add(tasksPath);
 
+  const featureLedger = (relFeature + '/cost-ledger.json').replace(/^\.\//, '');
+  if (fs.existsSync(path.join(rootPath, featureLedger))) filesSet.add(featureLedger);
+  if (fs.existsSync(path.join(rootPath, 'cost-ledger.json'))) filesSet.add('cost-ledger.json');
+  if (fs.existsSync(path.join(rootPath, '.gemstack/cost-ledger.json'))) filesSet.add('.gemstack/cost-ledger.json');
+
+  const featureCapsule = (relFeature + '/context-capsule.json').replace(/^\.\//, '');
+  if (fs.existsSync(path.join(rootPath, featureCapsule))) filesSet.add(featureCapsule);
+  if (fs.existsSync(path.join(rootPath, '.gemstack/context-capsule.json'))) filesSet.add('.gemstack/context-capsule.json');
+
+  const featureSwarm = (relFeature + '/swarm.json').replace(/^\.\//, '');
+  if (fs.existsSync(path.join(rootPath, featureSwarm))) filesSet.add(featureSwarm);
+  if (fs.existsSync(path.join(rootPath, '.gemstack/swarm.json'))) filesSet.add('.gemstack/swarm.json');
+
+  const featureVqa = (relFeature + '/visual-qa.json').replace(/^\.\//, '');
+  if (fs.existsSync(path.join(rootPath, featureVqa))) filesSet.add(featureVqa);
+  if (fs.existsSync(path.join(rootPath, '.gemstack/visual-qa.json'))) filesSet.add('.gemstack/visual-qa.json');
+
   for (const b of (planBindings || [])) {
     if (b.file && fs.existsSync(path.join(rootPath, b.file))) {
       filesSet.add(b.file);