gemstack-ai 1.1.2 → 1.3.0

package/specs/templates/plan.md

@@ -47,3 +47,33 @@ ruta/archivo: [Razón]
 [
 ]
 ```
+
+## 7. Vinculación Física de Pruebas (Upgrade B)
+<!--
+  Vincula cada test_id canónico de spec.md a un archivo físico ejecutable por el runner correspondiente.
+-->
+```gemstack-test-bindings
+[
+  {
+    "test_id": "TEST-FEATURE-A01",
+    "runner": "node:test",
+    "file": "tests/feature.test.js"
+  }
+]
+```
+
+## 8. Gates de Cierre de Proyecto (Upgrade B)
+<!--
+  Declara scripts requeridos del package.json como compuertas obligatorias de cierre.
+-->
+```gemstack-closure-gates
+[
+  {
+    "id": "project-tests",
+    "type": "PACKAGE_SCRIPT",
+    "script": "test",
+    "requirement": "REQUIRED",
+    "waivable": false
+  }
+]
+```

package/specs/templates/spec.md

@@ -50,3 +50,21 @@
   }
 ]
 ```
+
+## 7. Matriz Mecánica de Pruebas de Aceptación (Upgrade B)
+<!--
+  Declara la matriz canónica de pruebas para cierre mecánico en el bloque gemstack-test-matrix.
+  Campos requeridos: id, category, layer, description, pass_criteria, gate (REQUIRED | SUPPLEMENTAL).
+-->
+```gemstack-test-matrix
+[
+  {
+    "id": "TEST-FEATURE-A01",
+    "category": "CORE",
+    "layer": "UNIT",
+    "description": "Verifica el comportamiento principal de la funcionalidad",
+    "pass_criteria": "Retorna resultado esperado bajo condiciones normales",
+    "gate": "REQUIRED"
+  }
+]
+```

package/specs/templates/tasks.md

@@ -1,3 +1,12 @@
+
+<!--
+  Sintaxis de Metadatos de Tareas (Upgrade B):
+  Para cada tarea ejecutable, añade comentarios HTML que declaren:
+  <!-- gemstack:validation_required=true|false -->
+  <!-- gemstack:tests=TEST-ID-1,TEST-ID-2 -->
+  <!-- gemstack:files=src/file.js,tests/file.test.js -->
+  <!-- gemstack:depends=T001,T002 -->
+-->
 # Tareas de Implementación
 
 <!--

package/src/cli.js

@@ -9,6 +9,9 @@ const showCommand = require('./commands/show');
 const hooksCommand = require('./commands/hooks');
 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');
 
 async function main() {
     const { command, args, flags } = parser.parse(process.argv);
@@ -20,6 +23,8 @@ Commands:
   update    Update Gemstack-owned files
   doctor    Check health of the installation
   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
   list      List available skills
   show      Show content of a skill
   handoff   Show content of handoff.md
@@ -42,6 +47,9 @@ Options:
             case 'doctor': await doctorCommand(flags); break;
             case 'verify':
             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 'list': await listCommand(flags); break;
             case 'show': await showCommand(args[0], flags); break;
             case 'hooks': hooksCommand.installHooks(flags.target); break;

package/src/commands/collect.js

@@ -0,0 +1,340 @@
+const fs = require('fs');
+const path = require('path');
+const fssafe = require('../lib/filesystem-safe');
+const logger = require('../lib/logger');
+const { hashFile } = require('../lib/hasher');
+const { readState } = require('../lib/state');
+const {
+  extractTestMatrixBlock,
+  validateTestMatrix,
+  computeAcceptanceSignature
+} = require('../lib/test-matrix');
+const {
+  parsePlanBindings,
+  parsePlanGates,
+  parseTaskMetadata,
+  reconcileTaskTraceability,
+  resolveRelevantFiles,
+  computeContentAggregateHash,
+  resolveRepositoryContext,
+  computeClosureContextHash
+} = require('../lib/closure-context');
+const {
+  executeNodeTestRunner,
+  parseNodeTestTap,
+  reconcileTestRun,
+  executePackageScriptGate,
+  generateClosureManifest
+} = require('../lib/runner-adapters');
+
+module.exports = async (flags = {}) => {
+  const targetDir = flags.target || process.cwd();
+  const state = readState(targetDir);
+
+  if (!state || !state.active_spec) {
+    logger.error('No active spec found in state.json.');
+    process.exit(1);
+  }
+
+  const activeSpec = state.active_spec;
+  const specDir = fssafe.resolveSafe(targetDir, activeSpec);
+  const specFile = path.join(specDir, 'spec.md');
+  const planFile = path.join(specDir, 'plan.md');
+  const tasksFile = path.join(specDir, 'tasks.md');
+
+  if (!fs.existsSync(specFile)) {
+    logger.error(`spec.md not found at ${specFile}`);
+    process.exit(1);
+  }
+
+  logger.info(`Iniciando recolección mecánica de evidencias para: ${activeSpec}`);
+
+  // 1. Parse SPEC test matrix
+  const specContent = fs.readFileSync(specFile, 'utf8');
+  const { matrix, isLegacy } = extractTestMatrixBlock(specContent);
+
+  if (isLegacy) {
+    logger.info(`[LEGACY] Spec "${activeSpec}" opera en modo legacy sin matriz de pruebas.`);
+    return;
+  }
+
+  let canonicalMatrix;
+  let acceptanceSignature;
+  try {
+    canonicalMatrix = validateTestMatrix(matrix);
+    acceptanceSignature = computeAcceptanceSignature(canonicalMatrix);
+    logger.ok(`Matriz de pruebas validada (${canonicalMatrix.length} pruebas canónicas, signature: ${acceptanceSignature.slice(0, 12)}...)`);
+  } catch (e) {
+    logger.error(`Error validando matriz de pruebas: ${e.message}`);
+    process.exit(1);
+  }
+
+  // 2. Parse PLAN bindings and gates
+  let planBindings = [];
+  let planGates = [];
+  if (fs.existsSync(planFile)) {
+    const planContent = fs.readFileSync(planFile, 'utf8');
+    try {
+      planBindings = parsePlanBindings(planContent);
+      planGates = parsePlanGates(planContent);
+      logger.ok(`Bindings de plan parseados (${planBindings.length} bindings, ${planGates.length} gates).`);
+    } catch (e) {
+      logger.error(`Error parseando plan.md: ${e.message}`);
+      process.exit(1);
+    }
+  } else {
+    logger.error(`plan.md no encontrado en ${planFile}`);
+    process.exit(1);
+  }
+
+  // 3. Parse TASKS metadata & traceability
+  let tasks = [];
+  let traceability = {
+    summary: {
+      tasks_total: 0,
+      tasks_with_validation: 0,
+      tasks_documentation_only: 0,
+      unmapped_canonical_tests: []
+    },
+    unmappedCanonical: [],
+    reverseMap: {}
+  };
+  if (fs.existsSync(tasksFile)) {
+    const tasksContent = fs.readFileSync(tasksFile, 'utf8');
+    try {
+      tasks = parseTaskMetadata(tasksContent);
+      traceability = reconcileTaskTraceability(canonicalMatrix, tasks);
+      if (traceability.unmappedCanonical.length === 0) {
+        logger.ok(`Trazabilidad TASK <-> TEST confirmada (${tasks.length} tareas totales).`);
+      } else {
+        logger.warn(`Pruebas canónicas no mapeadas a tareas: ${traceability.unmappedCanonical.join(', ')}`);
+      }
+    } catch (e) {
+      logger.error(`Error parseando tasks.md: ${e.message}`);
+      process.exit(1);
+    }
+  }
+
+  // 4. Execute Test Runner on bound files
+  const boundTestFiles = Array.from(new Set(planBindings.map(b => b.file)));
+  logger.info(`Ejecutando runner sobre ${boundTestFiles.length} archivo(s) de prueba vinculados...`);
+
+  const startTime = Date.now();
+  let runnerResult;
+  try {
+    runnerResult = await executeNodeTestRunner(targetDir, boundTestFiles);
+  } catch (e) {
+    logger.error(`Fallo crítico ejecutando test runner: ${e.message}`);
+    runnerResult = { exitCode: 1, stdout: '', stderr: e.message };
+  }
+  const runnerDuration = Date.now() - startTime;
+
+  const tapSummary = parseNodeTestTap(runnerResult.stdout);
+  const reconciliation = reconcileTestRun(canonicalMatrix, planBindings, tapSummary.tests);
+
+  logger.ok(`Runner completado (exitCode: ${runnerResult.exitCode}, physical: ${tapSummary.physicalTotal}, passed: ${tapSummary.passed}, failed: ${tapSummary.failed})`);
+
+  // 5. Execute Required & Supplemental Gates
+  const requiredGateResults = {};
+  const supplementalGateResults = {};
+  const blockers = [];
+  const warnings = [];
+
+  for (const gate of planGates) {
+    logger.info(`Ejecutando gate "${gate.id}" (${gate.type}: ${gate.script})...`);
+    if (gate.type === 'PACKAGE_SCRIPT') {
+      const gateRes = await executePackageScriptGate(targetDir, gate);
+      const passed = gateRes.exitCode === 0;
+      const status = passed ? 'PASS' : 'FAIL';
+
+      if (gate.requirement === 'REQUIRED') {
+        requiredGateResults[gate.id] = status;
+        if (!passed) {
+          blockers.push({
+            code: 'REQUIRED_GATE_FAILED',
+            gate: gate.id,
+            message: `Required gate "${gate.id}" failed with exit code ${gateRes.exitCode}`,
+            waivable: gate.waivable
+          });
+        }
+      } else {
+        supplementalGateResults[gate.id] = status;
+        if (!passed) {
+          warnings.push({
+            code: 'SUPPLEMENTAL_GATE_FAILED',
+            gate: gate.id,
+            message: `Supplemental gate "${gate.id}" failed with exit code ${gateRes.exitCode}`
+          });
+        }
+      }
+    }
+  }
+
+  // Check reconciliation anomalies
+  if (!reconciliation.mathValid) {
+    blockers.push({
+      code: 'CLOSURE_RECONCILIATION_FAILURE',
+      message: 'Arithmetic count mismatch between executed canonical/supporting events and total physical events'
+    });
+  }
+
+  for (const m of reconciliation.missing) {
+    blockers.push({
+      code: 'REQUIRED_TEST_MISSING',
+      canonicalId: m,
+      message: `Required canonical test "${m}" is missing a physical binding in plan.md`
+    });
+  }
+
+  for (const ne of reconciliation.notExecuted) {
+    blockers.push({
+      code: 'REQUIRED_TEST_NOT_EXECUTED',
+      canonicalId: ne,
+      message: `Required canonical test "${ne}" was bound in plan.md but not executed in test runner`
+    });
+  }
+
+  for (const ph of reconciliation.phantoms) {
+    blockers.push({
+      code: 'PHANTOM_TEST',
+      canonicalId: ph,
+      message: `Claimed test "${ph}" was absent from runner execution traces`
+    });
+  }
+
+  for (const orp of reconciliation.orphans) {
+    blockers.push({
+      code: 'ORPHAN_TEST',
+      canonicalId: orp,
+      message: `Physical test claimed canonical ID "${orp}" which is absent from spec.md matrix`
+    });
+  }
+
+  for (const dup of reconciliation.duplicates) {
+    blockers.push({
+      code: 'DUPLICATE_TEST_BINDING',
+      canonicalId: dup,
+      message: `Multiple physical tests claimed the same canonical ID "${dup}"`
+    });
+  }
+
+  // Check physical failures
+  const executedCanonicalPassed = tapSummary.tests.filter(t => t.id && t.rawOutcome === 'PASS');
+  const executedCanonicalFailed = tapSummary.tests.filter(t => t.id && t.rawOutcome === 'FAIL');
+  for (const f of executedCanonicalFailed) {
+    blockers.push({
+      code: 'REQUIRED_TEST_FAILED',
+      canonicalId: f.id,
+      message: `Required canonical test "${f.id}" failed during execution`
+    });
+  }
+
+  // Transfer traceability unmapped errors if any
+  for (const unmappedId of traceability.unmappedCanonical) {
+    blockers.push({
+      code: 'UNMAPPED_CANONICAL_TEST',
+      canonicalId: unmappedId,
+      message: `Required canonical test "${unmappedId}" is not bound to any implementation task`
+    });
+  }
+
+  // 6. Compute Closure Context Hash & Manifest
+  const repoContext = resolveRepositoryContext(targetDir);
+
+  const phaseHashes = {
+    spec: hashFile(specFile),
+    plan: hashFile(planFile),
+    tasks: fs.existsSync(tasksFile) ? hashFile(tasksFile) : null
+  };
+
+  const relevantFiles = resolveRelevantFiles(targetDir, activeSpec, planBindings, tasks, planGates);
+  const relevantFilesDigest = computeContentAggregateHash(targetDir, relevantFiles);
+
+  const testFilesHash = computeContentAggregateHash(targetDir, boundTestFiles);
+  const implementationFiles = Array.from(new Set(tasks.flatMap(t => t.files || [])))
+    .filter(f => !f.endsWith('closure.json'));
+  const implementationContextHash = computeContentAggregateHash(targetDir, implementationFiles);
+  const requiredGateDefinitionHash = computeContentAggregateHash(targetDir, ['package.json']);
+
+  const contextObj = {
+    version: 1,
+    repository: repoContext,
+    phase_hashes: phaseHashes,
+    acceptance_signature: acceptanceSignature,
+    test_files_hash: testFilesHash,
+    implementation_context_hash: implementationContextHash,
+    required_gate_definition_hash: requiredGateDefinitionHash
+  };
+
+  const closureContextHash = computeClosureContextHash(contextObj);
+
+  // Status determination
+  let status = 'VERIFIED';
+  if (blockers.length > 0) {
+    status = 'BLOCKED';
+  }
+
+  const manifestData = {
+    feature: activeSpec,
+    generated_at: new Date().toISOString(),
+    status,
+    closure_context: {
+      closure_context_hash: closureContextHash,
+      repository_type: repoContext.type,
+      git_commit: repoContext.commit,
+      working_tree_clean: repoContext.working_tree_clean,
+      relevant_files_digest: relevantFilesDigest
+    },
+    acceptance_signature: acceptanceSignature,
+    canonical_summary: {
+      required_total: canonicalMatrix.filter(c => c.gate === 'REQUIRED').length,
+      required_passed: executedCanonicalPassed.length,
+      supplemental_total: canonicalMatrix.filter(c => c.gate === 'SUPPLEMENTAL').length,
+      supplemental_passed: 0
+    },
+    physical_summary: {
+      supporting_total: reconciliation.supportingCount,
+      supporting_passed: reconciliation.supportingCount - (tapSummary.failed - executedCanonicalFailed.length),
+      total_executed: tapSummary.physicalTotal,
+      total_passed: tapSummary.passed,
+      total_failed: tapSummary.failed,
+      total_skipped: tapSummary.skipped + tapSummary.todo + tapSummary.cancelled
+    },
+    reconciliation: {
+      math_valid: reconciliation.mathValid,
+      phantoms_detected: reconciliation.phantoms.length,
+      orphans_detected: reconciliation.orphans.length,
+      missing_canonical_ids: reconciliation.missing
+    },
+    task_traceability_summary: {
+      tasks_total: tasks.length,
+      tasks_with_validation: traceability.summary.tasks_with_validation,
+      tasks_documentation_only: traceability.summary.tasks_documentation_only,
+      unmapped_canonical_tests: traceability.unmappedCanonical
+    },
+    required_gates: requiredGateResults,
+    supplemental_gates: supplementalGateResults,
+    exceptions: [],
+    evidence_sources: [
+      {
+        type: 'PACKAGE_SCRIPT',
+        script: 'test',
+        runner: 'node:test',
+        exit_code: runnerResult.exitCode,
+        duration_ms: runnerDuration
+      }
+    ],
+    blockers,
+    warnings
+  };
+
+  if (flags.dryRun) {
+    logger.info('[DRY RUN] Manifest generado en memoria (no persistido en disco):');
+    console.log(JSON.stringify(manifestData, null, 2));
+    return manifestData;
+  }
+
+  const writtenManifest = generateClosureManifest(specDir, manifestData);
+  logger.ok(`Manifest de cierre persistido en: ${path.join(specDir, 'closure.json')} (status: ${status})`);
+  return writtenManifest;
+};

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 = 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/ship.js

@@ -0,0 +1,79 @@
+const fs = require('fs');
+const path = require('path');
+const fssafe = require('../lib/filesystem-safe');
+const logger = require('../lib/logger');
+const { readState, writeStateAtomic } = require('../lib/state');
+const { extractTestMatrixBlock } = require('../lib/test-matrix');
+
+module.exports = async (flags = {}) => {
+  const targetDir = flags.target || process.cwd();
+  const state = readState(targetDir);
+
+  if (!state || !state.active_spec) {
+    const err = new Error('No active spec found to ship');
+    err.code = 'NO_ACTIVE_SPEC';
+    throw err;
+  }
+
+  const activeSpec = state.active_spec;
+  const specDir = fssafe.resolveSafe(targetDir, activeSpec);
+  const specFile = path.join(specDir, 'spec.md');
+
+  if (!fs.existsSync(specFile)) {
+    const err = new Error(`spec.md not found at ${specFile}`);
+    err.code = 'SPEC_NOT_FOUND';
+    throw err;
+  }
+
+  const specContent = fs.readFileSync(specFile, 'utf8');
+  const { matrix, isLegacy } = extractTestMatrixBlock(specContent);
+
+  if (isLegacy) {
+    logger.info(`[LEGACY] Spec "${activeSpec}" opera en modo legacy sin matriz de pruebas.`);
+    // Transition lifecycle
+    state.last_completed_feature = activeSpec;
+    state.active_spec = null;
+    state.current_phase = 'shipped';
+    state.status = 'SHIPPED';
+    state.last_update = new Date().toISOString();
+    writeStateAtomic(targetDir, state);
+    logger.ok(`Feature "${activeSpec}" enviada exitosamente en modo legacy.`);
+    return { shipped: true, legacy: true, feature: activeSpec };
+  }
+
+  // Structured Upgrade B closure verification
+  const closurePath = path.join(specDir, 'closure.json');
+  if (!fs.existsSync(closurePath)) {
+    const err = new Error(`Cannot ship "${activeSpec}": closure.json not found. Run "gemstack collect" first.`);
+    err.code = 'CLOSURE_MANIFEST_MISSING';
+    throw err;
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(closurePath, 'utf8'));
+  } catch (e) {
+    const err = new Error(`Failed to parse closure.json: ${e.message}`);
+    err.code = 'CLOSURE_MANIFEST_INVALID';
+    throw err;
+  }
+
+  const allowedStatuses = ['VERIFIED', 'VERIFIED_WITH_EXCEPTIONS'];
+  if (!allowedStatuses.includes(manifest.status)) {
+    const blockersSummary = (manifest.blockers || []).map(b => b.code || b.message).join(', ');
+    const err = new Error(`Cannot ship "${activeSpec}": closure status is "${manifest.status}". Blockers: ${blockersSummary || 'none'}`);
+    err.code = 'CLOSURE_NOT_VERIFIED';
+    throw err;
+  }
+
+  // Transition lifecycle to SHIPPED
+  state.last_completed_feature = activeSpec;
+  state.active_spec = null;
+  state.current_phase = 'shipped';
+  state.status = 'SHIPPED';
+  state.last_update = new Date().toISOString();
+  writeStateAtomic(targetDir, state);
+
+  logger.ok(`Feature "${activeSpec}" verificada mecánicamente y enviada exitosamente (status: ${manifest.status}).`);
+  return { shipped: true, legacy: false, feature: activeSpec, status: manifest.status };
+};