gemstack-ai 1.3.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

@@ -12,6 +12,8 @@ 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);
@@ -25,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
@@ -50,6 +55,9 @@ Options:
             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

@@ -11,7 +11,7 @@ async function contextCommand(args = [], flags = {}) {
   const subcommand = args[0] || 'show';
   const targetDir = flags.target ? path.resolve(flags.target) : process.cwd();
 
-  let activeSpec = flags.feature;
+  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)) {

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

@@ -430,6 +430,44 @@ module.exports = async (flags) => {
         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) {
@@ -343,6 +343,14 @@ function resolveRelevantFiles(rootPath, featureDir, planBindings, taskList, plan
   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);