Feature/error governance

.aiox-core/constitution.md

@@ -105,23 +105,42 @@ Qualidade não é negociável. Todo código passa por múltiplos gates antes de
 
 ### VI. Absolute Imports (SHOULD)
 
-Imports relativos criam acoplamento e dificultam refatoração.
+Relative imports create coupling and make refactoring difficult.
 
-**Regras:**
-- SHOULD: Sempre usar imports absolutos com alias `@/`
-- SHOULD NOT: Usar imports relativos (`../../../`)
-- EXCEPTION: Imports dentro do mesmo módulo/feature podem ser relativos
+**Rules:**
+- SHOULD: Always use absolute imports with the `@/` alias.
+- SHOULD NOT: Use relative imports (`../../../`).
+- EXCEPTION: Imports within the same module/feature may be relative.
 
-**Exemplo:**
+**Example:**
 ```typescript
-// CORRETO
+// CORRECT
 import { useStore } from '@/stores/feature/store'
 
-// INCORRETO
+// INCORRECT
 import { useStore } from '../../../stores/feature/store'
 ```
 
-**Gate:** ESLint rule (já implementado)
+**Gate:** ESLint rule (already implemented)
+
+---
+
+### VII. Error Governance (MUST)
+
+All errors must be traceable, persistent, and categorized to ensure framework observability.
+
+**Rules:**
+- MUST: All errors must be registered and persisted via `ErrorRegistry`.
+- MUST NOT: Empty `catch` blocks are strictly prohibited; errors must be at least logged.
+- MUST: Categorize errors as `OPERATIONAL` (validation/user-info) or `SYSTEM` (framework bugs/agent failures).
+- MUST: Include contextual metadata (Agent ID, Action, and Timestamp) in every log.
+
+**Hierarchy:**
+```
+System Errors (Critical/Red) → Operational Errors (Audit/Yellow) → Info (Blue)
+```
+
+**Gate:** `scripts/quality/pr-review-ai.js` - BLOCK if raw `console.error` or empty `catch` detected.
 
 ---
 

.aiox-core/core/config/config-loader.js

@@ -78,6 +78,9 @@ const performanceMetrics = {
 
 /**
  * Checks if cache is still valid
+ *
+ * @returns {boolean} True if cache is valid
+ * @private
  */
 function isCacheValid() {
   if (!configCache.lastLoad) return false;
@@ -90,6 +93,9 @@ function isCacheValid() {
 
 /**
  * Loads full config file (used for initial load or cache refresh)
+ *
+ * @returns {Promise<Object>} The full configuration object
+ * @private
  */
 async function loadFullConfig() {
   const configPath = path.join('.aiox-core', 'core-config.yaml');
@@ -123,6 +129,7 @@ async function loadFullConfig() {
  *
  * @param {string[]} sections - Array of section names to load
  * @returns {Promise<Object>} Config object with requested sections
+ * @public
  */
 async function loadConfigSections(sections) {
   const startTime = Date.now();
@@ -164,15 +171,14 @@ async function loadConfigSections(sections) {
  *
  * @param {string} agentId - Agent ID (e.g., 'dev', 'qa', 'po')
  * @returns {Promise<Object>} Config object with sections needed by agent
+ * @public
  */
 async function loadAgentConfig(agentId) {
   const startTime = Date.now();
 
   // Get required sections for this agent
   const requiredSections = agentRequirements[agentId] || ALWAYS_LOADED;
 
-  console.log(`📦 Loading config for @${agentId} (${requiredSections.length} sections)...`);
-
   const config = await loadConfigSections(requiredSections);
 
   const loadTime = Date.now() - startTime;
@@ -189,13 +195,17 @@ async function loadAgentConfig(agentId) {
  * Loads always-loaded sections (minimal config)
  *
  * @returns {Promise<Object>} Minimal config with always-loaded sections
+ * @public
  */
 async function loadMinimalConfig() {
   return await loadConfigSections(ALWAYS_LOADED);
 }
 
 /**
  * Preloads config into cache (useful for startup optimization)
+ *
+ * @returns {Promise<void>}
+ * @public
  */
 async function preloadConfig() {
   console.log('🔄 Preloading config into cache...');
@@ -205,6 +215,9 @@ async function preloadConfig() {
 
 /**
  * Clears config cache (useful for testing or forcing reload)
+ *
+ * @returns {void}
+ * @public
  */
 function clearCache() {
   configCache.full = null;
@@ -217,6 +230,7 @@ function clearCache() {
  * Gets performance metrics
  *
  * @returns {Object} Performance statistics
+ * @public
  */
 function getPerformanceMetrics() {
   return {
@@ -233,6 +247,7 @@ function getPerformanceMetrics() {
  *
  * @param {string} agentId - Agent ID to validate
  * @returns {Promise<Object>} Validation result
+ * @public
  */
 async function validateAgentConfig(agentId) {
   const requiredSections = agentRequirements[agentId] || ALWAYS_LOADED;
@@ -257,6 +272,7 @@ async function validateAgentConfig(agentId) {
  *
  * @param {string} sectionName - Section to load
  * @returns {Promise<any>} Section content
+ * @public
  */
 async function getConfigSection(sectionName) {
   const config = await loadConfigSections([sectionName]);
@@ -277,3 +293,20 @@ module.exports = {
   agentRequirements,
   ALWAYS_LOADED,
 };
+ents,
+  ALWAYS_LOADED,
+};
+ getConfigSection,
+  agentRequirements,
+  ALWAYS_LOADED,
+};
+onfig,
+  loadFullConfig,
+  preloadConfig,
+  clearCache,
+  getPerformanceMetrics,
+  validateAgentConfig,
+  getConfigSection,
+  agentRequirements,
+  ALWAYS_LOADED,
+};

.aiox-core/core/config/config-resolver.js

@@ -30,6 +30,8 @@ const yaml = require('js-yaml');
 const { deepMerge } = require('./merge-utils');
 const { interpolateEnvVars, lintEnvPatterns } = require('./env-interpolator');
 const { globalConfigCache } = require('./config-cache');
+const AIOXError = require('aiox-core/utils/aiox-error');
+const ErrorRegistry = require('aiox-core/monitor/error-registry');
 
 // ---------------------------------------------------------------------------
 // JSON Schema validation (Story 12.2)
@@ -52,6 +54,7 @@ const SCHEMA_FILES = {
  * Get or create the shared Ajv instance (lazy-loaded).
  *
  * @returns {Object} Ajv instance
+ * @private
  */
 function getAjvInstance() {
   if (!_ajvInstance) {
@@ -68,6 +71,7 @@ function getAjvInstance() {
  *
  * @param {string} schemaFileName - Schema file name
  * @returns {Object|null} Parsed schema or null if not found
+ * @private
  */
 function loadSchema(schemaFileName) {
   if (_schemaCache[schemaFileName]) {
@@ -98,6 +102,7 @@ function loadSchema(schemaFileName) {
  * @param {Object} data - Config data to validate
  * @param {string} filePath - Source file path (for error messages)
  * @returns {string[]} Validation warnings (empty if valid)
+ * @private
  */
 function validateConfig(level, data, filePath) {
   const warnings = [];
@@ -132,6 +137,9 @@ function validateConfig(level, data, filePath) {
 
 /**
  * Clear the schema cache (useful for testing).
+ *
+ * @returns {void}
+ * @private
  */
 function clearSchemaCache() {
   _schemaCache = {};
@@ -173,6 +181,7 @@ const LEVELS = {
  * @param {string} projectRoot - Project root directory
  * @param {string} relativePath - Path relative to projectRoot
  * @returns {{ data: Object|null, path: string }} Parsed YAML or null
+ * @private
  */
 function loadYaml(projectRoot, relativePath) {
   const fullPath = path.join(projectRoot, relativePath);
@@ -186,7 +195,10 @@ function loadYaml(projectRoot, relativePath) {
     const data = yaml.load(content) || {};
     return { data, path: fullPath };
   } catch (error) {
-    throw new Error(`Failed to parse YAML at ${fullPath}: ${error.message}`);
+    throw new AIOXError(`Failed to parse YAML at ${fullPath}: ${error.message}`, {
+      category: 'SYSTEM',
+      metadata: { path: fullPath, originalError: error.message },
+    });
   }
 }
 
@@ -196,6 +208,7 @@ function loadYaml(projectRoot, relativePath) {
  *
  * @param {string} absolutePath - Absolute file path
  * @returns {{ data: Object|null, path: string }} Parsed YAML or null
+ * @private
  */
 function loadYamlAbsolute(absolutePath) {
   try {
@@ -224,6 +237,7 @@ function loadYamlAbsolute(absolutePath) {
  *
  * @param {string} projectRoot - Project root directory
  * @returns {boolean} True if legacy mode
+ * @public
  */
 function isLegacyMode(projectRoot) {
   const hasLegacy = fs.existsSync(path.join(projectRoot, CONFIG_FILES.legacy));
@@ -245,10 +259,8 @@ function isLegacyMode(projectRoot) {
  * @param {Object} options - Load options
  * @param {string} [options.appDir] - App directory for L3 config
  * @param {boolean} [options.debug] - Collect source-tracking metadata
- * @returns {Object} result
- * @returns {Object} result.config - Merged configuration
- * @returns {Object} [result.sources] - Per-key source tracking (when debug=true)
- * @returns {string[]} result.warnings - Lint/interpolation warnings
+ * @returns {Object} Result object containing config, sources, and warnings
+ * @public
  */
 function loadLayeredConfig(projectRoot, options = {}) {
   const warnings = [];
@@ -350,16 +362,18 @@ function loadLayeredConfig(projectRoot, options = {}) {
  * Load configuration in legacy mode (monolithic core-config.yaml).
  *
  * @param {string} projectRoot - Project root directory
- * @returns {Object} result
- * @returns {Object} result.config - Parsed configuration
- * @returns {string[]} result.warnings - Deprecation warnings
+ * @returns {Object} Result object containing config, sources, and warnings
+ * @public
  */
 function loadLegacyConfig(projectRoot) {
   const warnings = [];
   const legacy = loadYaml(projectRoot, CONFIG_FILES.legacy);
 
   if (!legacy.data) {
-    throw new Error(`Legacy config file not found: ${CONFIG_FILES.legacy}`);
+    throw new AIOXError(`Legacy config file not found: ${CONFIG_FILES.legacy}`, {
+      category: 'SYSTEM',
+      metadata: { projectRoot, path: CONFIG_FILES.legacy },
+    });
   }
 
   const suppressDeprecation = process.env.AIOX_SUPPRESS_DEPRECATION === 'true'
@@ -389,6 +403,8 @@ function loadLegacyConfig(projectRoot) {
  * @param {string} level - Level label (L1, L2, Pro, L3, L4)
  * @param {string} file - Source file path
  * @param {string} [prefix] - Key prefix for nested tracking
+ * @returns {void}
+ * @private
  */
 function trackSources(sources, data, level, file, prefix = '') {
   if (!sources || !data) return;
@@ -422,11 +438,8 @@ function trackSources(sources, data, level, file, prefix = '') {
  * @param {string} [options.appDir] - App directory for L3 (monorepo)
  * @param {boolean} [options.debug] - Enable source tracking
  * @param {boolean} [options.skipCache] - Bypass cache
- * @returns {Object} result
- * @returns {Object} result.config - Final resolved config
- * @returns {Object} [result.sources] - Source tracking (debug only)
- * @returns {string[]} result.warnings - All warnings
- * @returns {boolean} result.legacy - Whether legacy mode was used
+ * @returns {Object} Result object containing config, sources, warnings, and legacy flag
+ * @public
  */
 function resolveConfig(projectRoot, options = {}) {
   const cacheKey = `resolved:${projectRoot}:${options.appDir || 'root'}:${options.debug ? 'debug' : 'std'}`;
@@ -470,6 +483,7 @@ function resolveConfig(projectRoot, options = {}) {
  * @param {Object} [options] - Options
  * @param {string} [options.appDir] - App directory for level 'app'
  * @returns {Object|null} Raw config or null if file doesn't exist
+ * @public
  */
 function getConfigAtLevel(projectRoot, level, options = {}) {
   let relativePath;
@@ -499,7 +513,10 @@ function getConfigAtLevel(projectRoot, level, options = {}) {
       relativePath = CONFIG_FILES.legacy;
       break;
     default:
-      throw new Error(`Unknown config level: ${level}`);
+      throw new AIOXError(`Unknown config level: ${level}`, {
+        category: 'SYSTEM',
+        metadata: { level, projectRoot },
+      });
   }
 
   const { data } = loadYaml(projectRoot, relativePath);
@@ -519,6 +536,7 @@ const VALID_USER_PROFILES = ['bob', 'advanced'];
  * Ensure the ~/.aiox/ directory exists with secure permissions.
  *
  * @returns {string} Path to ~/.aiox/ directory
+ * @private
  */
 function ensureUserConfigDir() {
   const dir = path.dirname(CONFIG_FILES.user);
@@ -536,6 +554,7 @@ function ensureUserConfigDir() {
  * @param {string} key - Config key to set
  * @param {*} value - Value to set
  * @returns {Object} Updated user config
+ * @public
  */
 function setUserConfigValue(key, value) {
   ensureUserConfigDir();
@@ -552,19 +571,28 @@ function setUserConfigValue(key, value) {
 
   config[key] = value;
 
-  const yamlContent = yaml.dump(config, { lineWidth: -1 });
-  fs.writeFileSync(CONFIG_FILES.user, yamlContent, 'utf8');
+  try {
+    const yamlContent = yaml.dump(config, { lineWidth: -1 });
+    fs.writeFileSync(CONFIG_FILES.user, yamlContent, 'utf8');
 
-  globalConfigCache.clear();
+    globalConfigCache.clear();
 
-  return config;
+    return config;
+  } catch (error) {
+    ErrorRegistry.log(error, {
+      category: 'SYSTEM',
+      metadata: { key, value, path: CONFIG_FILES.user },
+    }).catch(() => {});
+    throw error;
+  }
 }
 
 /**
  * Toggle user_profile between 'bob' and 'advanced'.
  * Reads current value, flips it, writes back, and invalidates cache.
  *
  * @returns {{ previous: string, current: string }} Previous and new profile values
+ * @public
  */
 function toggleUserProfile() {
   let config = {};

.aiox-core/core/orchestration/executors/epic-4-executor.js

@@ -35,7 +35,7 @@ class Epic4Executor extends EpicExecutor {
   _getPlanTracker() {
     if (!this._planTracker) {
       try {
-        const PlanTracker = require('../../infrastructure/scripts/plan-tracker');
+        const { PlanTracker } = require('../../../infrastructure/scripts/plan-tracker');
         this._planTracker = PlanTracker;
       } catch (error) {
         this._log(`PlanTracker not available: ${error.message}`, 'warn');
@@ -51,7 +51,7 @@ class Epic4Executor extends EpicExecutor {
   _getSubtaskVerifier() {
     if (!this._subtaskVerifier) {
       try {
-        const SubtaskVerifier = require('../../infrastructure/scripts/subtask-verifier');
+        const { SubtaskVerifier } = require('../../../infrastructure/scripts/subtask-verifier');
         this._subtaskVerifier = SubtaskVerifier;
       } catch (error) {
         this._log(`SubtaskVerifier not available: ${error.message}`, 'warn');