scene-capability-engine 3.3.26 → 3.4.5

package/lib/commands/errorbook.js

@@ -11,6 +11,8 @@ const ERRORBOOK_ENTRY_API_VERSION = 'sce.errorbook.entry/v0.1';
 const ERRORBOOK_REGISTRY_API_VERSION = 'sce.errorbook.registry/v0.1';
 const ERRORBOOK_REGISTRY_CACHE_API_VERSION = 'sce.errorbook.registry-cache/v0.1';
 const ERRORBOOK_REGISTRY_INDEX_API_VERSION = 'sce.errorbook.registry-index/v0.1';
+const ERRORBOOK_INCIDENT_INDEX_API_VERSION = 'sce.errorbook.incident-index/v0.1';
+const ERRORBOOK_INCIDENT_API_VERSION = 'sce.errorbook.incident/v0.1';
 const ERRORBOOK_STATUSES = Object.freeze(['candidate', 'verified', 'promoted', 'deprecated']);
 const TEMPORARY_MITIGATION_TAG = 'temporary-mitigation';
 const DEFAULT_ERRORBOOK_REGISTRY_CONFIG = '.sce/config/errorbook-registry.json';
@@ -65,11 +67,16 @@ const HIGH_RISK_SIGNAL_TAGS = Object.freeze([
 
 function resolveErrorbookPaths(projectPath = process.cwd()) {
   const baseDir = path.join(projectPath, '.sce', 'errorbook');
+  const stagingDir = path.join(baseDir, 'staging');
   return {
     projectPath,
     baseDir,
     entriesDir: path.join(baseDir, 'entries'),
-    indexFile: path.join(baseDir, 'index.json')
+    indexFile: path.join(baseDir, 'index.json'),
+    stagingDir,
+    incidentsDir: path.join(stagingDir, 'incidents'),
+    resolvedDir: path.join(stagingDir, 'resolved'),
+    incidentIndexFile: path.join(stagingDir, 'index.json')
   };
 }
 
@@ -417,6 +424,247 @@ async function writeErrorbookEntry(paths, entry, fileSystem = fs) {
   return entryPath;
 }
 
+function buildDefaultIncidentIndex() {
+  return {
+    api_version: ERRORBOOK_INCIDENT_INDEX_API_VERSION,
+    updated_at: nowIso(),
+    total_incidents: 0,
+    incidents: []
+  };
+}
+
+function normalizeIncidentState(value, fallback = 'open') {
+  const normalized = normalizeText(value).toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+  if (normalized === 'open' || normalized === 'resolved') {
+    return normalized;
+  }
+  return fallback;
+}
+
+function shouldResolveIncidentByStatus(status = '') {
+  const normalized = normalizeStatus(status, 'candidate');
+  return normalized === 'verified' || normalized === 'promoted' || normalized === 'deprecated';
+}
+
+function createIncidentId() {
+  return `ebi-${Date.now()}-${crypto.randomBytes(3).toString('hex')}`;
+}
+
+function createIncidentAttemptId() {
+  return `attempt-${Date.now()}-${crypto.randomBytes(2).toString('hex')}`;
+}
+
+function buildIncidentFilePath(paths, incidentId) {
+  return path.join(paths.incidentsDir, `${incidentId}.json`);
+}
+
+function buildIncidentResolvedSnapshotPath(paths, incidentId) {
+  return path.join(paths.resolvedDir, `${incidentId}.json`);
+}
+
+async function ensureIncidentStorage(paths, fileSystem = fs) {
+  await fileSystem.ensureDir(paths.incidentsDir);
+  await fileSystem.ensureDir(paths.resolvedDir);
+  if (!await fileSystem.pathExists(paths.incidentIndexFile)) {
+    await fileSystem.writeJson(paths.incidentIndexFile, buildDefaultIncidentIndex(), { spaces: 2 });
+  }
+}
+
+async function readIncidentIndex(paths, fileSystem = fs) {
+  await ensureIncidentStorage(paths, fileSystem);
+  const payload = await fileSystem.readJson(paths.incidentIndexFile).catch(() => null);
+  if (!payload || typeof payload !== 'object' || !Array.isArray(payload.incidents)) {
+    return buildDefaultIncidentIndex();
+  }
+  return {
+    api_version: payload.api_version || ERRORBOOK_INCIDENT_INDEX_API_VERSION,
+    updated_at: normalizeText(payload.updated_at) || nowIso(),
+    total_incidents: Number.isInteger(payload.total_incidents) ? payload.total_incidents : payload.incidents.length,
+    incidents: payload.incidents
+  };
+}
+
+async function writeIncidentIndex(paths, index, fileSystem = fs) {
+  const payload = {
+    api_version: ERRORBOOK_INCIDENT_INDEX_API_VERSION,
+    updated_at: nowIso(),
+    incidents: Array.isArray(index.incidents) ? index.incidents : []
+  };
+  payload.total_incidents = payload.incidents.length;
+  await fileSystem.ensureDir(path.dirname(paths.incidentIndexFile));
+  await fileSystem.writeJson(paths.incidentIndexFile, payload, { spaces: 2 });
+  return payload;
+}
+
+async function readIncident(paths, incidentId, fileSystem = fs) {
+  const filePath = buildIncidentFilePath(paths, incidentId);
+  if (!await fileSystem.pathExists(filePath)) {
+    return null;
+  }
+  return fileSystem.readJson(filePath);
+}
+
+async function writeIncident(paths, incident, fileSystem = fs) {
+  const filePath = buildIncidentFilePath(paths, incident.id);
+  await fileSystem.ensureDir(path.dirname(filePath));
+  await fileSystem.writeJson(filePath, incident, { spaces: 2 });
+  return filePath;
+}
+
+function createIncidentAttemptSignature(payload = {}) {
+  const basis = JSON.stringify({
+    root_cause: normalizeText(payload.root_cause),
+    fix_actions: normalizeStringList(payload.fix_actions),
+    verification_evidence: normalizeStringList(payload.verification_evidence),
+    notes: normalizeText(payload.notes),
+    source: {
+      spec: normalizeText(payload?.source?.spec),
+      files: normalizeStringList(payload?.source?.files),
+      tests: normalizeStringList(payload?.source?.tests)
+    }
+  });
+  return crypto.createHash('sha1').update(basis).digest('hex').slice(0, 16);
+}
+
+function createIncidentSummaryFromIncident(incident = {}) {
+  return {
+    id: incident.id,
+    fingerprint: normalizeText(incident.fingerprint),
+    title: normalizeText(incident.title),
+    symptom: normalizeText(incident.symptom),
+    state: normalizeIncidentState(incident.state, 'open'),
+    attempt_count: Number(incident.attempt_count || 0),
+    created_at: normalizeText(incident.created_at),
+    updated_at: normalizeText(incident.updated_at),
+    last_attempt_at: normalizeText(incident.last_attempt_at),
+    resolved_at: normalizeText(incident.resolved_at),
+    linked_entry_id: normalizeText(incident?.resolution?.entry_id || '')
+  };
+}
+
+async function syncIncidentLoopForRecord(paths, payload = {}, entry = {}, options = {}, fileSystem = fs) {
+  await ensureIncidentStorage(paths, fileSystem);
+  const incidentIndex = await readIncidentIndex(paths, fileSystem);
+  const fingerprint = normalizeText(payload.fingerprint || entry.fingerprint);
+  const title = normalizeText(payload.title || entry.title);
+  const symptom = normalizeText(payload.symptom || entry.symptom);
+  const currentTime = normalizeText(options.nowIso) || nowIso();
+
+  let incidentSummary = incidentIndex.incidents.find((item) => item.fingerprint === fingerprint) || null;
+  let incident = incidentSummary ? await readIncident(paths, incidentSummary.id, fileSystem) : null;
+
+  if (!incident) {
+    const incidentId = incidentSummary ? incidentSummary.id : createIncidentId();
+    incident = {
+      api_version: ERRORBOOK_INCIDENT_API_VERSION,
+      id: incidentId,
+      fingerprint,
+      title,
+      symptom,
+      state: 'open',
+      created_at: currentTime,
+      updated_at: currentTime,
+      last_attempt_at: '',
+      resolved_at: '',
+      attempt_count: 0,
+      attempts: [],
+      resolution: {
+        entry_id: '',
+        status: '',
+        quality_score: 0,
+        resolved_at: ''
+      },
+      tags: [],
+      ontology_tags: []
+    };
+  }
+
+  const existingAttempts = Array.isArray(incident.attempts) ? incident.attempts : [];
+  const attemptNo = existingAttempts.length + 1;
+  const attemptSignature = createIncidentAttemptSignature(payload);
+  const duplicateOf = existingAttempts.find((item) => normalizeText(item.signature) === attemptSignature);
+  const attempt = {
+    id: createIncidentAttemptId(),
+    attempt_no: attemptNo,
+    recorded_at: currentTime,
+    signature: attemptSignature,
+    duplicate_of_attempt_no: duplicateOf ? Number(duplicateOf.attempt_no || 0) : 0,
+    entry_status: normalizeStatus(entry.status, 'candidate'),
+    quality_score: Number(entry.quality_score || scoreQuality(entry)),
+    root_cause: normalizeText(payload.root_cause || entry.root_cause),
+    fix_actions: normalizeStringList(payload.fix_actions || entry.fix_actions),
+    verification_evidence: normalizeStringList(payload.verification_evidence || entry.verification_evidence),
+    tags: normalizeStringList(payload.tags || entry.tags),
+    ontology_tags: normalizeOntologyTags(payload.ontology_tags || entry.ontology_tags),
+    notes: normalizeText(payload.notes || entry.notes),
+    source: {
+      spec: normalizeText(payload?.source?.spec || entry?.source?.spec),
+      files: normalizeStringList(payload?.source?.files || entry?.source?.files),
+      tests: normalizeStringList(payload?.source?.tests || entry?.source?.tests)
+    }
+  };
+
+  incident.attempts = [...existingAttempts, attempt];
+  incident.attempt_count = incident.attempts.length;
+  incident.title = title || incident.title;
+  incident.symptom = symptom || incident.symptom;
+  incident.tags = normalizeStringList(incident.tags, attempt.tags);
+  incident.ontology_tags = normalizeOntologyTags(incident.ontology_tags, attempt.ontology_tags);
+  incident.last_attempt_at = currentTime;
+  incident.updated_at = currentTime;
+
+  const resolveIncident = shouldResolveIncidentByStatus(entry.status);
+  if (resolveIncident) {
+    incident.state = 'resolved';
+    incident.resolved_at = currentTime;
+    incident.resolution = {
+      entry_id: normalizeText(entry.id),
+      status: normalizeStatus(entry.status, 'candidate'),
+      quality_score: Number(entry.quality_score || scoreQuality(entry)),
+      resolved_at: currentTime
+    };
+  } else {
+    incident.state = 'open';
+    incident.resolved_at = '';
+    incident.resolution = {
+      entry_id: '',
+      status: '',
+      quality_score: 0,
+      resolved_at: ''
+    };
+  }
+
+  await writeIncident(paths, incident, fileSystem);
+  if (incident.state === 'resolved') {
+    const resolvedSnapshotPath = buildIncidentResolvedSnapshotPath(paths, incident.id);
+    await fileSystem.ensureDir(path.dirname(resolvedSnapshotPath));
+    await fileSystem.writeJson(resolvedSnapshotPath, incident, { spaces: 2 });
+  }
+
+  const summary = createIncidentSummaryFromIncident(incident);
+  const summaryIndex = incidentIndex.incidents.findIndex((item) => item.id === summary.id);
+  if (summaryIndex >= 0) {
+    incidentIndex.incidents[summaryIndex] = summary;
+  } else {
+    incidentIndex.incidents.push(summary);
+  }
+  incidentIndex.incidents.sort((left, right) => `${right.updated_at || ''}`.localeCompare(`${left.updated_at || ''}`));
+  await writeIncidentIndex(paths, incidentIndex, fileSystem);
+
+  return {
+    incident: summary,
+    latest_attempt: {
+      id: attempt.id,
+      attempt_no: attempt.attempt_no,
+      duplicate_of_attempt_no: attempt.duplicate_of_attempt_no,
+      signature: attempt.signature
+    }
+  };
+}
+
 function scoreQuality(entry = {}) {
   let score = 0;
 
@@ -1380,12 +1628,16 @@ async function runErrorbookRecordCommand(options = {}, dependencies = {}) {
   }
   index.entries.sort((left, right) => `${right.updated_at}`.localeCompare(`${left.updated_at}`));
   await writeErrorbookIndex(paths, index, fileSystem);
+  const incidentLoop = await syncIncidentLoopForRecord(paths, normalized, entry, {
+    nowIso: entry.updated_at
+  }, fileSystem);
 
   const result = {
     mode: 'errorbook-record',
     created,
     deduplicated,
-    entry
+    entry,
+    incident_loop: incidentLoop
   };
 
   if (options.json) {
@@ -1735,6 +1987,127 @@ async function runErrorbookRegistryHealthCommand(options = {}, dependencies = {}
   return result;
 }
 
+function findIncidentSummaryById(index, id) {
+  const normalized = normalizeText(id);
+  if (!normalized) {
+    return null;
+  }
+  const exact = index.incidents.find((item) => item.id === normalized);
+  if (exact) {
+    return exact;
+  }
+  const startsWith = index.incidents.filter((item) => item.id.startsWith(normalized));
+  if (startsWith.length === 1) {
+    return startsWith[0];
+  }
+  if (startsWith.length > 1) {
+    throw new Error(`incident id prefix "${normalized}" is ambiguous (${startsWith.length} matches)`);
+  }
+  return null;
+}
+
+async function runErrorbookIncidentListCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const paths = resolveErrorbookPaths(projectPath);
+  const index = await readIncidentIndex(paths, fileSystem);
+
+  const stateFilter = normalizeText(options.state).toLowerCase();
+  if (stateFilter && !['open', 'resolved'].includes(stateFilter)) {
+    throw new Error('incident state must be one of: open, resolved');
+  }
+  const limit = Number.isFinite(Number(options.limit)) && Number(options.limit) > 0
+    ? Number(options.limit)
+    : 20;
+
+  let incidents = [...index.incidents];
+  if (stateFilter) {
+    incidents = incidents.filter((item) => normalizeIncidentState(item.state) === stateFilter);
+  }
+  incidents.sort((left, right) => `${right.updated_at || ''}`.localeCompare(`${left.updated_at || ''}`));
+
+  const result = {
+    mode: 'errorbook-incident-list',
+    total_incidents: index.incidents.length,
+    total_results: incidents.length,
+    incidents: incidents.slice(0, limit)
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!options.silent) {
+    if (result.incidents.length === 0) {
+      console.log(chalk.gray('No staging incidents found'));
+    } else {
+      const table = new Table({
+        head: ['ID', 'State', 'Attempts', 'Title', 'Updated'].map((item) => chalk.cyan(item)),
+        colWidths: [20, 12, 10, 56, 24]
+      });
+      result.incidents.forEach((incident) => {
+        table.push([
+          incident.id,
+          incident.state,
+          Number(incident.attempt_count || 0),
+          normalizeText(incident.title).length > 52
+            ? `${normalizeText(incident.title).slice(0, 52)}...`
+            : normalizeText(incident.title),
+          incident.updated_at || ''
+        ]);
+      });
+      console.log(table.toString());
+      console.log(chalk.gray(`Total: ${result.total_results} (stored: ${result.total_incidents})`));
+    }
+  }
+
+  return result;
+}
+
+async function runErrorbookIncidentShowCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const paths = resolveErrorbookPaths(projectPath);
+  const index = await readIncidentIndex(paths, fileSystem);
+
+  const id = normalizeText(options.id || options.incidentId);
+  if (!id) {
+    throw new Error('incident id is required');
+  }
+
+  const summary = findIncidentSummaryById(index, id);
+  if (!summary) {
+    throw new Error(`staging incident not found: ${id}`);
+  }
+
+  const incident = await readIncident(paths, summary.id, fileSystem);
+  if (!incident) {
+    throw new Error(`staging incident file not found: ${summary.id}`);
+  }
+
+  const result = {
+    mode: 'errorbook-incident-show',
+    incident
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!options.silent) {
+    console.log(chalk.cyan.bold(incident.title || summary.title || summary.id));
+    console.log(chalk.gray(`id: ${incident.id}`));
+    console.log(chalk.gray(`state: ${incident.state}`));
+    console.log(chalk.gray(`attempts: ${Number(incident.attempt_count || 0)}`));
+    console.log(chalk.gray(`fingerprint: ${incident.fingerprint}`));
+    console.log(chalk.gray(`updated_at: ${incident.updated_at}`));
+    if (incident.state === 'resolved') {
+      console.log(chalk.gray(`resolved_at: ${incident.resolved_at || '(none)'}`));
+      if (incident.resolution && incident.resolution.entry_id) {
+        console.log(chalk.gray(`linked_entry: ${incident.resolution.entry_id}`));
+      }
+    }
+  }
+
+  return result;
+}
+
 async function runErrorbookListCommand(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
   const fileSystem = dependencies.fileSystem || fs;
@@ -2299,6 +2672,36 @@ function registerErrorbookCommands(program) {
       }
     });
 
+  const incident = errorbook
+    .command('incident')
+    .description('Inspect temporary trial-and-error incident loop before final curation');
+
+  incident
+    .command('list')
+    .description('List staging incidents')
+    .option('--state <state>', 'Filter incident state (open|resolved)')
+    .option('--limit <n>', 'Maximum incidents returned', parseInt, 20)
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runErrorbookIncidentListCommand(options);
+      } catch (error) {
+        emitCommandError(error, options.json);
+      }
+    });
+
+  incident
+    .command('show <id>')
+    .description('Show a staging incident with all attempts')
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async (id, options) => {
+      try {
+        await runErrorbookIncidentShowCommand({ ...options, id });
+      } catch (error) {
+        emitCommandError(error, options.json);
+      }
+    });
+
   errorbook
     .command('list')
     .description('List curated errorbook entries')
@@ -2470,6 +2873,8 @@ module.exports = {
   HIGH_RISK_SIGNAL_TAGS,
   DEBUG_EVIDENCE_TAGS,
   DEFAULT_PROMOTE_MIN_QUALITY,
+  ERRORBOOK_INCIDENT_INDEX_API_VERSION,
+  ERRORBOOK_INCIDENT_API_VERSION,
   resolveErrorbookPaths,
   resolveErrorbookRegistryPaths,
   normalizeOntologyTags,
@@ -2481,6 +2886,8 @@ module.exports = {
   runErrorbookExportCommand,
   runErrorbookSyncRegistryCommand,
   runErrorbookRegistryHealthCommand,
+  runErrorbookIncidentListCommand,
+  runErrorbookIncidentShowCommand,
   runErrorbookListCommand,
   runErrorbookShowCommand,
   runErrorbookFindCommand,

package/lib/commands/spec-domain.js

@@ -3,7 +3,8 @@ const path = require('path');
 const chalk = require('chalk');
 const {
   ensureSpecDomainArtifacts,
-  validateSpecDomainArtifacts
+  validateSpecDomainArtifacts,
+  analyzeSpecDomainCoverage
 } = require('../spec/domain-modeling');
 
 function normalizeText(value) {
@@ -109,18 +110,29 @@ async function runSpecDomainValidateCommand(options = {}, dependencies = {}) {
   await assertSpecExists(projectPath, specId, fileSystem);
 
   const validation = await validateSpecDomainArtifacts(projectPath, specId, fileSystem);
+  const coverage = await analyzeSpecDomainCoverage(projectPath, specId, fileSystem);
   const payload = {
     mode: 'spec-domain-validate',
     spec_id: specId,
     passed: validation.passed,
     ratio: validation.ratio,
     details: validation.details,
-    warnings: validation.warnings
+    warnings: validation.warnings,
+    coverage: {
+      passed: coverage.passed,
+      coverage_ratio: coverage.coverage_ratio,
+      covered_count: coverage.covered_count,
+      total_count: coverage.total_count,
+      uncovered: coverage.uncovered
+    }
   };
 
   if (options.failOnError && !validation.passed) {
     throw new Error(`spec domain validation failed: ${validation.warnings.join('; ')}`);
   }
+  if (options.failOnGap && !coverage.passed) {
+    throw new Error(`spec domain coverage has gaps: ${coverage.uncovered.join(', ')}`);
+  }
 
   if (options.json) {
     console.log(JSON.stringify(payload, null, 2));
@@ -138,6 +150,49 @@ async function runSpecDomainValidateCommand(options = {}, dependencies = {}) {
   return payload;
 }
 
+async function runSpecDomainCoverageCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const specId = resolveSpecId(options);
+  if (!specId) {
+    throw new Error('--spec is required');
+  }
+  await assertSpecExists(projectPath, specId, fileSystem);
+
+  const coverage = await analyzeSpecDomainCoverage(projectPath, specId, fileSystem);
+  const payload = {
+    mode: 'spec-domain-coverage',
+    spec_id: specId,
+    passed: coverage.passed,
+    coverage_ratio: coverage.coverage_ratio,
+    covered_count: coverage.covered_count,
+    total_count: coverage.total_count,
+    uncovered: coverage.uncovered,
+    items: coverage.items
+  };
+
+  if (options.failOnGap && !coverage.passed) {
+    throw new Error(`spec domain coverage has gaps: ${coverage.uncovered.join(', ')}`);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else if (!options.silent) {
+    if (coverage.passed) {
+      console.log(chalk.green('✓ Spec domain closed-loop coverage passed'));
+    } else {
+      console.log(chalk.red('✗ Spec domain closed-loop coverage has gaps'));
+      coverage.items
+        .filter((item) => !item.covered)
+        .forEach((item) => {
+          console.log(chalk.gray(`  - ${item.id}: ${item.label}`));
+        });
+    }
+  }
+
+  return payload;
+}
+
 function registerSpecDomainCommand(program) {
   const specDomain = program
     .command('spec-domain')
@@ -194,6 +249,7 @@ function registerSpecDomainCommand(program) {
     .description('Validate problem-domain artifacts for a Spec')
     .requiredOption('--spec <name>', 'Spec identifier')
     .option('--fail-on-error', 'Exit non-zero when validation fails')
+    .option('--fail-on-gap', 'Exit non-zero when closed-loop coverage is incomplete')
     .option('--json', 'Output machine-readable JSON')
     .action(async (options) => {
       try {
@@ -207,11 +263,31 @@ function registerSpecDomainCommand(program) {
         process.exit(1);
       }
     });
+
+  specDomain
+    .command('coverage')
+    .description('Analyze scene-closed-loop research coverage for a Spec')
+    .requiredOption('--spec <name>', 'Spec identifier')
+    .option('--fail-on-gap', 'Exit non-zero when closed-loop coverage is incomplete')
+    .option('--json', 'Output machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runSpecDomainCoverageCommand(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ spec-domain coverage failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
 }
 
 module.exports = {
   runSpecDomainInitCommand,
   runSpecDomainRefreshCommand,
   runSpecDomainValidateCommand,
+  runSpecDomainCoverageCommand,
   registerSpecDomainCommand
 };