gemstack-ai 1.1.2 → 1.3.0

package/src/commands/verify.js

@@ -13,7 +13,7 @@ module.exports = async (flags) => {
     let totalWarnings = 0;
 
     // 1. Verificación Estructural y Manifest
-    logger.info('--- 1/5 Verificación Estructural (Archivos Base) ---');
+    logger.info('--- 1/6 Verificación Estructural (Archivos Base) ---');
     const manifestPath = fssafe.resolveSafe(targetDir, '.gemstack/manifest.json');
     if (!fs.existsSync(manifestPath)) {
         logger.warn('Manifest no encontrado (.gemstack/manifest.json). Es posible que Gemstack no esté inicializado en este directorio.');
@@ -58,7 +58,7 @@ module.exports = async (flags) => {
     }
 
     // 2. Verificación de Memoria (handoff.md)
-    logger.info('--- 2/5 Verificación de Memoria e Integridad de Handoff ---');
+    logger.info('--- 2/6 Verificación de Memoria e Integridad de Handoff ---');
     const handoffPath = fssafe.resolveSafe(targetDir, 'handoff.md');
     if (!fs.existsSync(handoffPath)) {
         logger.error('handoff.md no existe en la raíz. La memoria de sesión es obligatoria.');
@@ -90,7 +90,7 @@ module.exports = async (flags) => {
     }
 
     // 3. Consistencia de Estado Local (.gemstack/state.json)
-    logger.info('--- 3/5 Verificación de Estado Local (.gemstack/state.json) ---');
+    logger.info('--- 3/6 Verificación de Estado Local (.gemstack/state.json) ---');
     const statePath = fssafe.resolveSafe(targetDir, '.gemstack/state.json');
     let loadedState = null;
     if (!fs.existsSync(statePath)) {
@@ -119,7 +119,7 @@ module.exports = async (flags) => {
     }
 
     // 4. Consistencia de Arquitectura y Hashes de Fase (Upgrade A)
-    logger.info('--- 4/5 Verificación de Consistencia de Arquitectura y Hashes de Fase ---');
+    logger.info('--- 4/6 Verificación de Consistencia de Arquitectura y Hashes de Fase ---');
     if (loadedState && loadedState.active_spec) {
         try {
             const { hashFile } = require('../lib/hasher');
@@ -254,8 +254,184 @@ module.exports = async (flags) => {
         logger.ok('Sin spec activa configurada para verificación de contratos.');
     }
 
-    // 5. Seguridad Local y Anti-Silent Failures en Tests
-    logger.info('--- 5/5 Verificación de Seguridad y Test Runners ---');
+    // 5. Verificación de Evidencia de Cierre Mecánico (Upgrade B - Read-Only)
+    logger.info('--- 5/6 Verificación de Evidencia de Cierre Mecánico (Read-Only) ---');
+    if (loadedState && loadedState.active_spec) {
+        try {
+            const { extractTestMatrixBlock } = require('../lib/test-matrix');
+            const specFile = fssafe.resolveSafe(targetDir, path.join(loadedState.active_spec, 'spec.md'));
+
+            if (!fs.existsSync(specFile)) {
+                logger.ok(`Modo legacy: no existe spec.md en ${loadedState.active_spec}`);
+            } else {
+                const specContent = fs.readFileSync(specFile, 'utf8');
+                const { isLegacy } = extractTestMatrixBlock(specContent);
+
+                if (isLegacy) {
+                    logger.info(`[LEGACY] Spec "${loadedState.active_spec}" opera en modo legacy sin matriz de pruebas.`);
+                } else {
+                    // Feature structured: read closure.json in strictly read-only mode
+                    const specDir = fssafe.resolveSafe(targetDir, loadedState.active_spec);
+                    const closurePath = path.join(specDir, 'closure.json');
+
+                    if (!fs.existsSync(closurePath)) {
+                        logger.error(`[CLOSURE_MANIFEST_MISSING] closure.json no existe en ${loadedState.active_spec}. Ejecuta "gemstack collect" para generar la evidencia mecánica.`);
+                        totalErrors++;
+                    } else {
+                        let manifest;
+                        try {
+                            manifest = JSON.parse(fs.readFileSync(closurePath, 'utf8'));
+                        } catch (e) {
+                            logger.error(`[CLOSURE_MANIFEST_INVALID] closure.json tiene formato JSON inválido: ${e.message}`);
+                            totalErrors++;
+                            manifest = null;
+                        }
+
+                        if (manifest) {
+                            // Recompute closureContextHash in-memory without modifying any file
+                            const {
+                                validateTestMatrix,
+                                computeAcceptanceSignature
+                            } = require('../lib/test-matrix');
+                            const {
+                                parsePlanBindings,
+                                parsePlanGates,
+                                parseTaskMetadata,
+                                computeContentAggregateHash,
+                                resolveRepositoryContext,
+                                computeClosureContextHash
+                            } = require('../lib/closure-context');
+                            const { hashFile } = require('../lib/hasher');
+
+                            const planFile = path.join(specDir, 'plan.md');
+                            const tasksFile = path.join(specDir, 'tasks.md');
+
+                            let planBindings = [];
+                            let planGates = [];
+                            if (fs.existsSync(planFile)) {
+                                const planContent = fs.readFileSync(planFile, 'utf8');
+                                planBindings = parsePlanBindings(planContent);
+                                planGates = parsePlanGates(planContent);
+                            }
+
+                            let tasks = [];
+                            if (fs.existsSync(tasksFile)) {
+                                const tasksContent = fs.readFileSync(tasksFile, 'utf8');
+                                tasks = parseTaskMetadata(tasksContent);
+                            }
+
+                            const { matrix } = extractTestMatrixBlock(specContent);
+                            const canonicalMatrix = validateTestMatrix(matrix);
+                            const acceptanceSignature = computeAcceptanceSignature(canonicalMatrix);
+
+                            const repoContext = resolveRepositoryContext(targetDir);
+                            const phaseHashes = {
+                                spec: hashFile(specFile),
+                                plan: fs.existsSync(planFile) ? hashFile(planFile) : null,
+                                tasks: fs.existsSync(tasksFile) ? hashFile(tasksFile) : null
+                            };
+
+                            const boundTestFiles = Array.from(new Set(planBindings.map(b => b.file)));
+                            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 freshContextObj = {
+                                version: 1,
+                                repository: repoContext,
+                                phase_hashes: phaseHashes,
+                                acceptance_signature: acceptanceSignature,
+                                test_files_hash: testFilesHash,
+                                implementation_context_hash: implementationContextHash,
+                                required_gate_definition_hash: requiredGateDefinitionHash
+                            };
+
+                            const freshContextHash = computeClosureContextHash(freshContextObj);
+                            const recordedContextHash = manifest.closure_context ? manifest.closure_context.closure_context_hash : null;
+
+                            if (recordedContextHash !== freshContextHash) {
+                                logger.error(`[CLOSURE_EVIDENCE_STALE] La evidencia de cierre está desactualizada respecto al estado actual del proyecto. Re-ejecuta "gemstack collect". (Registrado: ${recordedContextHash ? recordedContextHash.slice(0, 12) : 'none'}..., Actual: ${freshContextHash.slice(0, 12)}...)`);
+                                totalErrors++;
+                            } else {
+                                logger.ok(`Frescura de evidencia de cierre verificada (${freshContextHash.slice(0, 12)}...).`);
+
+                                if (manifest.status !== 'VERIFIED' && manifest.status !== 'VERIFIED_WITH_EXCEPTIONS') {
+                                    logger.error(`[CLOSURE_NOT_VERIFIED] Estado del manifiesto es "${manifest.status}". Bloqueadores: ${JSON.stringify(manifest.blockers || [])}`);
+                                    totalErrors++;
+                                } else {
+                                    logger.ok(`Evidencia de cierre aprobada: status="${manifest.status}", ${manifest.canonical_summary ? manifest.canonical_summary.required_passed : 0}/${manifest.canonical_summary ? manifest.canonical_summary.required_total : 0} pruebas canónicas pasadas.`);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        } catch (mErr) {
+            logger.error(`Error en verificación de evidencia de cierre: ${mErr.message}`);
+            totalErrors++;
+        }
+    } else {
+        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.');
+    }
+
+    // 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');
     if (fs.existsSync(envPath)) {
         logger.warn('Archivo .env detectado en el directorio de trabajo. Verifica que esté en .gitignore.');

package/src/lib/closure-context.js

@@ -0,0 +1,453 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+const { hashFile, normalizePath, normalizeContent } = require('./hasher');
+
+function parsePlanBindings(planContent, canonicalMatrix) {
+  const normalized = normalizeContent(planContent);
+  const lines = normalized.split('\n');
+  const fence = String.fromCharCode(96, 96, 96);
+  const header = fence + 'gemstack-test-bindings';
+
+  const blocks = [];
+  let inBlock = false;
+  let blockLines = [];
+
+  for (const line of lines) {
+    if (!inBlock) {
+      if (line.trimEnd() === header) {
+        inBlock = true;
+        blockLines = [];
+      }
+    } else {
+      if (line.trimEnd() === fence) {
+        inBlock = false;
+        blocks.push(blockLines.join('\n'));
+      } else {
+        blockLines.push(line);
+      }
+    }
+  }
+
+  if (blocks.length === 0) {
+    return [];
+  }
+
+  if (blocks.length > 1) {
+    const err = new Error('Multiple gemstack-test-bindings blocks detected. Exactly one is permitted.');
+    err.code = 'BINDINGS_PARSE_ERROR';
+    throw err;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(blocks[0].trim());
+  } catch (e) {
+    const err = new Error('Failed to parse gemstack-test-bindings JSON: ' + e.message);
+    err.code = 'BINDINGS_PARSE_ERROR';
+    throw err;
+  }
+
+  if (!Array.isArray(parsed)) {
+    const err = new Error('gemstack-test-bindings must be a JSON array');
+    err.code = 'BINDINGS_PARSE_ERROR';
+    throw err;
+  }
+
+  const validCanonicalIds = new Set(canonicalMatrix ? canonicalMatrix.map(m => m.id) : []);
+  const seenTestIds = new Set();
+  const validated = [];
+
+  for (let i = 0; i < parsed.length; i++) {
+    const item = parsed[i];
+    if (!item || typeof item !== 'object') {
+      const err = new Error('Binding at index ' + i + ' must be an object');
+      err.code = 'BINDINGS_PARSE_ERROR';
+      throw err;
+    }
+
+    const testId = item.test_id || item.id;
+    if (!testId || typeof testId !== 'string') {
+      const err = new Error('Binding at index ' + i + ' missing test_id');
+      err.code = 'BINDINGS_PARSE_ERROR';
+      throw err;
+    }
+
+    if (validCanonicalIds.size > 0 && !validCanonicalIds.has(testId)) {
+      const err = new Error('Binding references unknown canonical ID: "' + testId + '"');
+      err.code = 'BINDINGS_PARSE_ERROR';
+      throw err;
+    }
+
+    if (seenTestIds.has(testId)) {
+      const err = new Error('Duplicate test_id binding detected: "' + testId + '"');
+      err.code = 'DUPLICATE_TEST_BINDING';
+      throw err;
+    }
+    seenTestIds.add(testId);
+
+    if (!item.file || typeof item.file !== 'string') {
+      const err = new Error('Binding for "' + testId + '" missing file');
+      err.code = 'BINDINGS_PARSE_ERROR';
+      throw err;
+    }
+
+    const normFile = item.file.replace(/\\/g, '/');
+    if (path.isAbsolute(normFile) || normFile.startsWith('../')) {
+      const err = new Error('Binding file must be repository-relative POSIX path: "' + item.file + '"');
+      err.code = 'BINDINGS_PARSE_ERROR';
+      throw err;
+    }
+
+    validated.push({
+      test_id: testId,
+      runner: item.runner || 'node:test',
+      file: normFile
+    });
+  }
+
+  return validated;
+}
+
+function parsePlanGates(planContent) {
+  const normalized = normalizeContent(planContent);
+  const lines = normalized.split('\n');
+  const fence = String.fromCharCode(96, 96, 96);
+  const header = fence + 'gemstack-closure-gates';
+
+  const blocks = [];
+  let inBlock = false;
+  let blockLines = [];
+
+  for (const line of lines) {
+    if (!inBlock) {
+      if (line.trimEnd() === header) {
+        inBlock = true;
+        blockLines = [];
+      }
+    } else {
+      if (line.trimEnd() === fence) {
+        inBlock = false;
+        blocks.push(blockLines.join('\n'));
+      } else {
+        blockLines.push(line);
+      }
+    }
+  }
+
+  if (blocks.length === 0) {
+    return [];
+  }
+
+  if (blocks.length > 1) {
+    const err = new Error('Multiple gemstack-closure-gates blocks detected. Exactly one is permitted.');
+    err.code = 'GATES_PARSE_ERROR';
+    throw err;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(blocks[0].trim());
+  } catch (e) {
+    const err = new Error('Failed to parse gemstack-closure-gates JSON: ' + e.message);
+    err.code = 'GATES_PARSE_ERROR';
+    throw err;
+  }
+
+  if (!Array.isArray(parsed)) {
+    const err = new Error('gemstack-closure-gates must be a JSON array');
+    err.code = 'GATES_PARSE_ERROR';
+    throw err;
+  }
+
+  const seenGateIds = new Set();
+  const validated = [];
+
+  for (let i = 0; i < parsed.length; i++) {
+    const item = parsed[i];
+    if (!item.id || typeof item.id !== 'string') {
+      const err = new Error('Gate at index ' + i + ' missing id');
+      err.code = 'GATES_PARSE_ERROR';
+      throw err;
+    }
+
+    if (seenGateIds.has(item.id)) {
+      const err = new Error('Duplicate gate id detected: "' + item.id + '"');
+      err.code = 'GATES_PARSE_ERROR';
+      throw err;
+    }
+    seenGateIds.add(item.id);
+
+    if (item.type !== 'PACKAGE_SCRIPT') {
+      const err = new Error('Unsupported gate type: "' + item.type + '". Only PACKAGE_SCRIPT is supported in MVP.');
+      err.code = 'GATES_PARSE_ERROR';
+      throw err;
+    }
+
+    if (!item.script || typeof item.script !== 'string') {
+      const err = new Error('PACKAGE_SCRIPT gate "' + item.id + '" missing script name');
+      err.code = 'GATES_PARSE_ERROR';
+      throw err;
+    }
+
+    if (!['REQUIRED', 'SUPPLEMENTAL'].includes(item.requirement)) {
+      const err = new Error('Gate "' + item.id + '" has invalid requirement: "' + item.requirement + '"');
+      err.code = 'GATES_PARSE_ERROR';
+      throw err;
+    }
+
+    if (item.requirement === 'REQUIRED' && typeof item.waivable !== 'boolean') {
+      const err = new Error('REQUIRED gate "' + item.id + '" requires explicit boolean waivable property');
+      err.code = 'GATES_PARSE_ERROR';
+      throw err;
+    }
+
+    validated.push({
+      id: item.id,
+      type: item.type,
+      script: item.script,
+      requirement: item.requirement,
+      waivable: typeof item.waivable === 'boolean' ? item.waivable : false
+    });
+  }
+
+  return validated;
+}
+
+function parseTaskMetadata(tasksContent) {
+  const normalized = normalizeContent(tasksContent);
+  const lines = normalized.split('\n');
+  const tasks = [];
+
+  const taskHeaderRegex = /^[*-]\s+\[[ xX]\]\s+\*\*(T\d+):\s*(.*?)\*\*/;
+  let currentTask = null;
+
+  for (const line of lines) {
+    const match = line.match(taskHeaderRegex);
+    if (match) {
+      if (currentTask) {
+        tasks.push(currentTask);
+      }
+      currentTask = {
+        id: match[1],
+        title: match[2].trim(),
+        validation_required: null,
+        tests: [],
+        files: [],
+        depends: []
+      };
+      continue;
+    }
+
+    if (currentTask) {
+      const vMatch = line.match(/<!--\s*gemstack:validation_required=(true|false)\s*-->/);
+      if (vMatch) {
+        currentTask.validation_required = vMatch[1] === 'true';
+        continue;
+      }
+      const tMatch = line.match(/<!--\s*gemstack:tests=(.*?)\s*-->/);
+      if (tMatch) {
+        currentTask.tests = tMatch[1] ? tMatch[1].split(',').map(s => s.trim()).filter(Boolean) : [];
+        continue;
+      }
+      const fMatch = line.match(/<!--\s*gemstack:files=(.*?)\s*-->/);
+      if (fMatch) {
+        currentTask.files = fMatch[1] ? fMatch[1].split(',').map(s => s.trim().replace(/\\/g, '/')).filter(Boolean) : [];
+        continue;
+      }
+      const dMatch = line.match(/<!--\s*gemstack:depends=(.*?)\s*-->/);
+      if (dMatch) {
+        currentTask.depends = dMatch[1] ? dMatch[1].split(',').map(s => s.trim()).filter(Boolean) : [];
+        continue;
+      }
+    }
+  }
+
+  if (currentTask) {
+    tasks.push(currentTask);
+  }
+
+  for (const t of tasks) {
+    if (t.validation_required === null) {
+      const err = new Error('Task ' + t.id + ' must explicitly declare validation_required');
+      err.code = 'TASK_VALIDATION_MISSING';
+      throw err;
+    }
+    if (t.validation_required && t.tests.length === 0) {
+      const err = new Error('Task ' + t.id + ' has validation_required=true but specifies no tests');
+      err.code = 'TASK_VALIDATION_MISSING';
+      throw err;
+    }
+  }
+
+  return tasks;
+}
+
+function reconcileTaskTraceability(canonicalMatrix, taskList) {
+  const reverseMap = {};
+  const tasksWithValidation = [];
+  const tasksDocOnly = [];
+
+  for (const t of taskList) {
+    if (t.validation_required) {
+      tasksWithValidation.push(t.id);
+      for (const testId of t.tests) {
+        if (!reverseMap[testId]) {
+          reverseMap[testId] = [];
+        }
+        reverseMap[testId].push(t.id);
+      }
+    } else {
+      tasksDocOnly.push(t.id);
+    }
+  }
+
+  const unmappedCanonical = [];
+  const requiredCanonical = canonicalMatrix.filter(m => m.gate === 'REQUIRED');
+
+  for (const c of requiredCanonical) {
+    if (!reverseMap[c.id] || reverseMap[c.id].length === 0) {
+      unmappedCanonical.push(c.id);
+    }
+  }
+
+  const summary = {
+    tasks_total: taskList.length,
+    tasks_with_validation: tasksWithValidation.length,
+    tasks_documentation_only: tasksDocOnly.length,
+    unmapped_canonical_tests: unmappedCanonical
+  };
+
+  return { summary, unmappedCanonical, reverseMap };
+}
+
+function resolveRelevantFiles(rootPath, featureDir, planBindings, taskList, planGates) {
+  const relFeature = normalizePath(featureDir, rootPath);
+  const filesSet = new Set();
+
+  const specPath = (relFeature + '/spec.md').replace(/^\.\//, '');
+  const planPath = (relFeature + '/plan.md').replace(/^\.\//, '');
+  const tasksPath = (relFeature + '/tasks.md').replace(/^\.\//, '');
+
+  if (fs.existsSync(path.join(rootPath, specPath))) filesSet.add(specPath);
+  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');
+
+  for (const b of (planBindings || [])) {
+    if (b.file && fs.existsSync(path.join(rootPath, b.file))) {
+      filesSet.add(b.file);
+    }
+  }
+
+  for (const t of (taskList || [])) {
+    for (const f of (t.files || [])) {
+      if (fs.existsSync(path.join(rootPath, f))) {
+        filesSet.add(f);
+      }
+    }
+  }
+
+  const hasPkgScript = (planGates || []).some(g => g.type === 'PACKAGE_SCRIPT');
+  if (hasPkgScript && fs.existsSync(path.join(rootPath, 'package.json'))) {
+    filesSet.add('package.json');
+  }
+
+  return Array.from(filesSet).sort((a, b) => (a < b ? -1 : (a > b ? 1 : 0)));
+}
+
+function computeContentAggregateHash(rootPath, filePaths) {
+  const sortedPaths = [...filePaths].sort((a, b) => (a < b ? -1 : (a > b ? 1 : 0)));
+  const entries = [];
+
+  for (const p of sortedPaths) {
+    const abs = path.join(rootPath, p);
+    if (fs.existsSync(abs)) {
+      entries.push({
+        path: p.replace(/\\/g, '/'),
+        hash: hashFile(abs)
+      });
+    }
+  }
+
+  const canonicalJson = JSON.stringify(entries);
+  return crypto.createHash('sha256').update(canonicalJson, 'utf8').digest('hex');
+}
+
+function resolveRepositoryContext(rootPath) {
+  const gitDir = path.join(rootPath, '.git');
+  if (!fs.existsSync(gitDir)) {
+    return {
+      type: 'non-git',
+      commit: null,
+      working_tree_clean: null
+    };
+  }
+
+  try {
+    const headCommit = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: rootPath,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8'
+    }).trim();
+
+    const statusOutput = execFileSync('git', ['status', '--porcelain'], {
+      cwd: rootPath,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8'
+    }).trim();
+
+    return {
+      type: 'git',
+      commit: headCommit,
+      working_tree_clean: statusOutput.length === 0
+    };
+  } catch (e) {
+    return {
+      type: 'git',
+      commit: null,
+      working_tree_clean: null
+    };
+  }
+}
+
+function computeClosureContextHash(contextObj) {
+  const sortedKeys = Object.keys(contextObj).sort((a, b) => (a < b ? -1 : (a > b ? 1 : 0)));
+  const normalized = {};
+
+  for (const k of sortedKeys) {
+    const val = contextObj[k];
+    if (val && typeof val === 'object' && !Array.isArray(val)) {
+      const subKeys = Object.keys(val).sort((a, b) => (a < b ? -1 : (a > b ? 1 : 0)));
+      normalized[k] = {};
+      for (const sk of subKeys) {
+        normalized[k][sk] = val[sk];
+      }
+    } else {
+      normalized[k] = val;
+    }
+  }
+
+  const canonicalJson = JSON.stringify(normalized);
+  return crypto.createHash('sha256').update(canonicalJson, 'utf8').digest('hex');
+}
+
+module.exports = {
+  parsePlanBindings,
+  parsePlanGates,
+  parseTaskMetadata,
+  reconcileTaskTraceability,
+  resolveRelevantFiles,
+  computeContentAggregateHash,
+  resolveRepositoryContext,
+  computeClosureContextHash
+};