scene-capability-engine 3.3.26 → 3.4.6

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';
@@ -46,6 +48,7 @@ const ONTOLOGY_TAG_ALIASES = Object.freeze({
   action_chain: 'execution_flow'
 });
 const DEFAULT_PROMOTE_MIN_QUALITY = 75;
+const DEFAULT_RELEASE_GATE_MIN_QUALITY = 70;
 const ERRORBOOK_RISK_LEVELS = Object.freeze(['low', 'medium', 'high']);
 const DEBUG_EVIDENCE_TAGS = Object.freeze([
   'debug-evidence',
@@ -65,11 +68,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 +425,266 @@ 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 attemptContract = payload && payload.attempt_contract && typeof payload.attempt_contract === 'object'
+    ? payload.attempt_contract
+    : {};
+  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),
+    attempt_contract: {
+      hypothesis: normalizeText(attemptContract.hypothesis),
+      change_points: normalizeStringList(attemptContract.change_points),
+      verification_result: normalizeText(attemptContract.verification_result),
+      rollback_point: normalizeText(attemptContract.rollback_point),
+      conclusion: normalizeText(attemptContract.conclusion)
+    },
+    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),
+    attempt_contract: {
+      hypothesis: normalizeText(payload?.attempt_contract?.hypothesis || entry?.attempt_contract?.hypothesis),
+      change_points: normalizeStringList(payload?.attempt_contract?.change_points || entry?.attempt_contract?.change_points),
+      verification_result: normalizeText(
+        payload?.attempt_contract?.verification_result || entry?.attempt_contract?.verification_result
+      ),
+      rollback_point: normalizeText(payload?.attempt_contract?.rollback_point || entry?.attempt_contract?.rollback_point),
+      conclusion: normalizeText(payload?.attempt_contract?.conclusion || entry?.attempt_contract?.conclusion)
+    },
+    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;
 
@@ -447,6 +715,19 @@ function scoreQuality(entry = {}) {
   if (normalizeText(entry.symptom).length >= 24 && normalizeText(entry.root_cause).length >= 24) {
     score += 2;
   }
+  const attemptContract = entry && typeof entry.attempt_contract === 'object'
+    ? entry.attempt_contract
+    : {};
+  const attemptContractComplete = Boolean(
+    normalizeText(attemptContract.hypothesis)
+    && normalizeStringList(attemptContract.change_points).length > 0
+    && normalizeText(attemptContract.verification_result)
+    && normalizeText(attemptContract.rollback_point)
+    && normalizeText(attemptContract.conclusion)
+  );
+  if (attemptContractComplete) {
+    score += 5;
+  }
 
   return Math.max(0, Math.min(100, score));
 }
@@ -464,6 +745,24 @@ function validateRecordPayload(payload) {
   if (!Array.isArray(payload.fix_actions) || payload.fix_actions.length === 0) {
     throw new Error('at least one --fix-action is required');
   }
+  const attemptContract = payload.attempt_contract && typeof payload.attempt_contract === 'object'
+    ? payload.attempt_contract
+    : {};
+  if (!normalizeText(attemptContract.hypothesis)) {
+    throw new Error('attempt contract requires hypothesis');
+  }
+  if (!Array.isArray(attemptContract.change_points) || attemptContract.change_points.length === 0) {
+    throw new Error('attempt contract requires change_points');
+  }
+  if (!normalizeText(attemptContract.verification_result)) {
+    throw new Error('attempt contract requires verification_result');
+  }
+  if (!normalizeText(attemptContract.rollback_point)) {
+    throw new Error('attempt contract requires rollback_point');
+  }
+  if (!normalizeText(attemptContract.conclusion)) {
+    throw new Error('attempt contract requires conclusion');
+  }
 
   const status = normalizeStatus(payload.status, 'candidate');
   if (status === 'promoted') {
@@ -559,6 +858,42 @@ function normalizeRecordPayload(options = {}, fromFilePayload = {}) {
     })
   };
 
+  const attemptContractFromFile = fromFilePayload && typeof fromFilePayload.attempt_contract === 'object'
+    ? fromFilePayload.attempt_contract
+    : {};
+  payload.attempt_contract = {
+    hypothesis: normalizeText(
+      options.attemptHypothesis
+      || attemptContractFromFile.hypothesis
+      || payload.root_cause
+    ),
+    change_points: normalizeStringList(
+      options.attemptChangePoints,
+      attemptContractFromFile.change_points,
+      attemptContractFromFile.changePoints,
+      payload.fix_actions
+    ),
+    verification_result: normalizeText(
+      options.attemptVerificationResult
+      || attemptContractFromFile.verification_result
+      || attemptContractFromFile.verificationResult
+      || (payload.verification_evidence[0] || '')
+      || 'pending-verification'
+    ),
+    rollback_point: normalizeText(
+      options.attemptRollbackPoint
+      || attemptContractFromFile.rollback_point
+      || attemptContractFromFile.rollbackPoint
+      || 'not-required'
+    ),
+    conclusion: normalizeText(
+      options.attemptConclusion
+      || attemptContractFromFile.conclusion
+      || payload.notes
+      || payload.root_cause
+    )
+  };
+
   return payload;
 }
 
@@ -624,6 +959,30 @@ function mergeEntry(existingEntry, incomingPayload) {
     ontology_tags: normalizeOntologyTags(existingEntry.ontology_tags, incomingPayload.ontology_tags),
     status: selectStatus(existingEntry.status, incomingPayload.status),
     notes: normalizeText(incomingPayload.notes) || existingEntry.notes || '',
+    attempt_contract: {
+      hypothesis: normalizeText(incomingPayload?.attempt_contract?.hypothesis)
+        || normalizeText(existingEntry?.attempt_contract?.hypothesis)
+        || normalizeText(incomingPayload.root_cause)
+        || normalizeText(existingEntry.root_cause),
+      change_points: normalizeStringList(
+        existingEntry?.attempt_contract?.change_points,
+        incomingPayload?.attempt_contract?.change_points,
+        incomingPayload.fix_actions
+      ),
+      verification_result: normalizeText(incomingPayload?.attempt_contract?.verification_result)
+        || normalizeText(existingEntry?.attempt_contract?.verification_result)
+        || normalizeStringList(incomingPayload.verification_evidence, existingEntry.verification_evidence)[0]
+        || '',
+      rollback_point: normalizeText(incomingPayload?.attempt_contract?.rollback_point)
+        || normalizeText(existingEntry?.attempt_contract?.rollback_point)
+        || 'not-required',
+      conclusion: normalizeText(incomingPayload?.attempt_contract?.conclusion)
+        || normalizeText(existingEntry?.attempt_contract?.conclusion)
+        || normalizeText(incomingPayload.notes)
+        || normalizeText(existingEntry.notes)
+        || normalizeText(incomingPayload.root_cause)
+        || normalizeText(existingEntry.root_cause)
+    },
     source: {
       spec: normalizeText(incomingPayload?.source?.spec) || normalizeText(existingEntry?.source?.spec),
       files: normalizeStringList(existingEntry?.source?.files, incomingPayload?.source?.files),
@@ -1147,7 +1506,7 @@ function evaluateEntryRisk(entry = {}) {
   if (hasHighRiskTag) {
     return 'high';
   }
-  if (status === 'candidate' && qualityScore >= 85) {
+  if (status === 'candidate' && qualityScore > 85) {
     return 'high';
   }
   if (status === 'candidate' && qualityScore >= 75 && ontologyTags.includes('decision_policy')) {
@@ -1156,7 +1515,7 @@ function evaluateEntryRisk(entry = {}) {
   if (status === 'candidate') {
     return 'medium';
   }
-  if (qualityScore >= 85 && ontologyTags.includes('decision_policy')) {
+  if (qualityScore > 85 && ontologyTags.includes('decision_policy')) {
     return 'high';
   }
   return 'medium';
@@ -1169,6 +1528,9 @@ async function evaluateErrorbookReleaseGate(options = {}, dependencies = {}) {
   const index = await readErrorbookIndex(paths, fileSystem);
   const minRisk = normalizeRiskLevel(options.minRisk || options.min_risk || 'high', 'high');
   const includeVerified = options.includeVerified === true;
+  const minQuality = Number.isFinite(Number(options.minQuality || options.min_quality))
+    ? Math.max(0, Math.min(100, Number(options.minQuality || options.min_quality)))
+    : DEFAULT_RELEASE_GATE_MIN_QUALITY;
 
   const inspected = [];
   const mitigationInspected = [];
@@ -1226,6 +1588,14 @@ async function evaluateErrorbookReleaseGate(options = {}, dependencies = {}) {
       block_reasons: ['risk_threshold']
     }));
 
+  const curationBlocked = inspected
+    .filter((item) => item.status === 'verified' && Number(item.quality_score || 0) < minQuality)
+    .map((item) => ({
+      ...item,
+      block_reasons: ['curation_quality'],
+      policy_violations: [`quality_score<${minQuality}`]
+    }));
+
   const blockedById = new Map();
   for (const item of riskBlocked) {
     blockedById.set(item.id, {
@@ -1249,6 +1619,19 @@ async function evaluateErrorbookReleaseGate(options = {}, dependencies = {}) {
     }
     blockedById.set(existing.id, existing);
   }
+  for (const item of curationBlocked) {
+    const existing = blockedById.get(item.id);
+    if (!existing) {
+      blockedById.set(item.id, {
+        ...item,
+        policy_violations: normalizeStringList(item.policy_violations)
+      });
+      continue;
+    }
+    existing.block_reasons = normalizeStringList(existing.block_reasons, item.block_reasons);
+    existing.policy_violations = normalizeStringList(existing.policy_violations, item.policy_violations);
+    blockedById.set(existing.id, existing);
+  }
 
   const blocked = Array.from(blockedById.values())
     .sort((left, right) => {
@@ -1271,12 +1654,14 @@ async function evaluateErrorbookReleaseGate(options = {}, dependencies = {}) {
     mode: 'errorbook-release-gate',
     gate: {
       min_risk: minRisk,
+      min_quality: minQuality,
       include_verified: includeVerified,
       mitigation_policy_enforced: true
     },
     passed: blocked.length === 0,
     inspected_count: inspected.length,
     risk_blocked_count: riskBlocked.length,
+    curation_blocked_count: curationBlocked.length,
     mitigation_inspected_count: mitigationInspected.length,
     mitigation_blocked_count: mitigationBlocked.length,
     blocked_count: blocked.length,
@@ -1361,6 +1746,7 @@ async function runErrorbookRecordCommand(options = {}, dependencies = {}) {
       source: normalized.source,
       temporary_mitigation: mitigationPayload,
       notes: normalized.notes || '',
+      attempt_contract: normalized.attempt_contract,
       occurrences: 1
     };
     entry.quality_score = scoreQuality(entry);
@@ -1380,12 +1766,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 +2125,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 +2810,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')
@@ -2420,6 +2961,7 @@ function registerErrorbookCommands(program) {
     .command('release-gate')
     .description('Block release on unresolved high-risk entries and temporary-mitigation policy violations')
     .option('--min-risk <level>', 'Risk threshold (low|medium|high)', 'high')
+    .option('--min-quality <n>', `Minimum quality for unresolved entries (default: ${DEFAULT_RELEASE_GATE_MIN_QUALITY})`, parseInt)
     .option('--include-verified', 'Also inspect verified (non-promoted) entries')
     .option('--fail-on-block', 'Exit with error when gate is blocked')
     .option('--json', 'Emit machine-readable JSON')
@@ -2470,6 +3012,9 @@ module.exports = {
   HIGH_RISK_SIGNAL_TAGS,
   DEBUG_EVIDENCE_TAGS,
   DEFAULT_PROMOTE_MIN_QUALITY,
+  DEFAULT_RELEASE_GATE_MIN_QUALITY,
+  ERRORBOOK_INCIDENT_INDEX_API_VERSION,
+  ERRORBOOK_INCIDENT_API_VERSION,
   resolveErrorbookPaths,
   resolveErrorbookRegistryPaths,
   normalizeOntologyTags,
@@ -2481,6 +3026,8 @@ module.exports = {
   runErrorbookExportCommand,
   runErrorbookSyncRegistryCommand,
   runErrorbookRegistryHealthCommand,
+  runErrorbookIncidentListCommand,
+  runErrorbookIncidentShowCommand,
   runErrorbookListCommand,
   runErrorbookShowCommand,
   runErrorbookFindCommand,