aios-core 4.2.14 → 4.3.0

package/.aios-core/core/code-intel/helpers/qa-helper.js

@@ -0,0 +1,187 @@
+'use strict';
+
+const { getEnricher, getClient, isCodeIntelAvailable } = require('../index');
+
+// Risk level thresholds based on blast radius (reference count)
+// Consistent with dev-helper.js
+const RISK_THRESHOLDS = {
+  LOW_MAX: 4,       // 0-4 refs = LOW
+  MEDIUM_MAX: 15,   // 5-15 refs = MEDIUM
+                     // >15 refs = HIGH
+};
+
+// Coverage status thresholds based on test reference count
+const COVERAGE_THRESHOLDS = {
+  INDIRECT_MAX: 2,  // 1-2 test refs = INDIRECT
+  MINIMAL_MAX: 5,   // 3-5 test refs = MINIMAL
+                     // >5 test refs = GOOD
+};
+
+/**
+ * QaHelper — Code intelligence helper for @qa agent tasks.
+ *
+ * All functions return null gracefully when no provider is available.
+ * Never throws — safe to call unconditionally in task workflows.
+ */
+
+/**
+ * Get blast radius and risk level for a set of files.
+ * Used by qa-gate to assess impact of changes in gate decisions.
+ *
+ * @param {string[]} files - Files to assess blast radius for
+ * @returns {Promise<{blastRadius: number, riskLevel: string, references: Array}|null>}
+ */
+async function getBlastRadius(files) {
+  if (!files || files.length === 0) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const enricher = getEnricher();
+    const impact = await enricher.assessImpact(files);
+
+    if (!impact) return null;
+
+    return {
+      blastRadius: impact.blastRadius,
+      riskLevel: _calculateRiskLevel(impact.blastRadius),
+      references: impact.references || [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get test coverage status for a list of symbols.
+ * Used by qa-gate to assess test coverage per modified function.
+ *
+ * @param {string[]} symbols - Symbol names to check test coverage for
+ * @returns {Promise<Array<{symbol: string, status: string, testCount: number, tests: Array}>|null>}
+ */
+async function getTestCoverage(symbols) {
+  if (!symbols || symbols.length === 0) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const enricher = getEnricher();
+    const results = await Promise.all(
+      symbols.map(async (symbol) => {
+        try {
+          const tests = await enricher.findTests(symbol);
+          const testCount = tests ? tests.length : 0;
+          return {
+            symbol,
+            status: _calculateCoverageStatus(testCount),
+            testCount,
+            tests: tests || [],
+          };
+        } catch {
+          return {
+            symbol,
+            status: 'NO_TESTS',
+            testCount: 0,
+            tests: [],
+          };
+        }
+      }),
+    );
+
+    return results;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get reference impact for a set of files — which consumers are affected.
+ * Used by qa-review-story to show consumers affected by each change.
+ *
+ * @param {string[]} files - Files to check reference impact for
+ * @returns {Promise<Array<{file: string, consumers: Array}>|null>}
+ */
+async function getReferenceImpact(files) {
+  if (!files || files.length === 0) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const client = getClient();
+    const results = await Promise.all(
+      files.map(async (file) => {
+        try {
+          const refs = await client.findReferences(file);
+          return {
+            file,
+            consumers: refs || [],
+          };
+        } catch {
+          return {
+            file,
+            consumers: [],
+          };
+        }
+      }),
+    );
+
+    return results;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Suggest gate influence based on blast radius risk level.
+ * Returns advisory message when HIGH risk detected — never changes verdict automatically.
+ *
+ * @param {string} riskLevel - Risk level from getBlastRadius ('LOW'|'MEDIUM'|'HIGH')
+ * @returns {{advisory: string, suggestedGate: string}|null}
+ */
+function suggestGateInfluence(riskLevel) {
+  if (!riskLevel) return null;
+
+  if (riskLevel === 'HIGH') {
+    return {
+      advisory: 'HIGH blast radius detected. Consider CONCERNS gate with additional review recommended.',
+      suggestedGate: 'CONCERNS',
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Calculate risk level from blast radius count.
+ * Consistent with dev-helper.js thresholds.
+ * @param {number} blastRadius - Number of references affected
+ * @returns {string} 'LOW' | 'MEDIUM' | 'HIGH'
+ * @private
+ */
+function _calculateRiskLevel(blastRadius) {
+  if (blastRadius <= RISK_THRESHOLDS.LOW_MAX) return 'LOW';
+  if (blastRadius <= RISK_THRESHOLDS.MEDIUM_MAX) return 'MEDIUM';
+  return 'HIGH';
+}
+
+/**
+ * Calculate coverage status from test reference count.
+ * @param {number} testCount - Number of test references found
+ * @returns {string} 'NO_TESTS' | 'INDIRECT' | 'MINIMAL' | 'GOOD'
+ * @private
+ */
+function _calculateCoverageStatus(testCount) {
+  if (testCount === 0) return 'NO_TESTS';
+  if (testCount <= COVERAGE_THRESHOLDS.INDIRECT_MAX) return 'INDIRECT';
+  if (testCount <= COVERAGE_THRESHOLDS.MINIMAL_MAX) return 'MINIMAL';
+  return 'GOOD';
+}
+
+module.exports = {
+  getBlastRadius,
+  getTestCoverage,
+  getReferenceImpact,
+  suggestGateInfluence,
+  // Exposed for testing
+  _calculateRiskLevel,
+  _calculateCoverageStatus,
+  RISK_THRESHOLDS,
+  COVERAGE_THRESHOLDS,
+};

package/.aios-core/core/code-intel/helpers/story-helper.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const { getEnricher, getClient, isCodeIntelAvailable } = require('../index');
+
+/**
+ * StoryHelper — Code intelligence helper for @sm/@po agent tasks.
+ *
+ * All functions return null gracefully when no provider is available.
+ * Never throws — safe to call unconditionally in task workflows.
+ *
+ * Functions:
+ *   - detectDuplicateStory(description) — for @sm story creation (advisory warning)
+ *   - suggestRelevantFiles(description) — for @sm story creation (file suggestions)
+ *   - validateNoDuplicates(description) — for @po story validation (checklist boolean)
+ */
+
+/**
+ * Detect duplicate stories/functionality in the codebase.
+ * Used by @sm during story creation — returns advisory warning only, never blocks.
+ *
+ * @param {string} description - Story description to check for duplicates
+ * @returns {Promise<{matches: Array, warning: string}|null>} Duplicate info or null
+ */
+async function detectDuplicateStory(description) {
+  if (!description) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const enricher = getEnricher();
+    const result = await enricher.detectDuplicates(description, { path: '.' });
+
+    if (!result || !result.matches || result.matches.length === 0) return null;
+
+    return {
+      matches: result.matches,
+      warning: _formatDuplicateWarning(result.matches),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Suggest relevant files for a new story based on description.
+ * Composes findReferences + analyzeCodebase for comprehensive file suggestions.
+ * Used by @sm during story creation to pre-populate "Suggested Files" section.
+ *
+ * @param {string} description - Story description to find relevant files for
+ * @returns {Promise<{files: Array, codebaseContext: Object|null}|null>} File suggestions or null
+ */
+async function suggestRelevantFiles(description) {
+  if (!description) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const client = getClient();
+
+    // Per-capability try/catch — partial results accepted
+    let files = null;
+    let codebaseContext = null;
+
+    try {
+      const refs = await client.findReferences(description);
+      if (refs) {
+        files = refs;
+      }
+    } catch { /* skip — partial result ok */ }
+
+    try {
+      const analysis = await client.analyzeCodebase('.');
+      if (analysis) {
+        codebaseContext = analysis;
+      }
+    } catch { /* skip — partial result ok */ }
+
+    // Return null only if we got nothing at all
+    if (!files && !codebaseContext) return null;
+
+    return {
+      files: files || [],
+      codebaseContext,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate that a story description does not duplicate existing functionality.
+ * Used by @po during story validation — returns boolean for checklist item.
+ *
+ * @param {string} description - Story description to validate
+ * @returns {Promise<{hasDuplicates: boolean, matches: Array, suggestion: string|null}|null>} Validation result or null
+ */
+async function validateNoDuplicates(description) {
+  if (!description) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const enricher = getEnricher();
+    const result = await enricher.detectDuplicates(description, { path: '.' });
+
+    if (!result) {
+      return {
+        hasDuplicates: false,
+        matches: [],
+        suggestion: null,
+      };
+    }
+
+    const hasDuplicates = result.matches && result.matches.length > 0;
+
+    return {
+      hasDuplicates,
+      matches: result.matches || [],
+      suggestion: hasDuplicates ? 'Consider ADAPT instead of CREATE — similar functionality exists' : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format a human-readable warning message from duplicate matches.
+ * @param {Array} matches - Array of duplicate match objects
+ * @returns {string} Formatted warning message
+ * @private
+ */
+function _formatDuplicateWarning(matches) {
+  if (!matches || matches.length === 0) return '';
+
+  const fileList = matches
+    .map((m) => m.file || m.path || 'unknown')
+    .slice(0, 5)
+    .join(', ');
+
+  return `Similar functionality already exists in: ${fileList}. Consider ADAPT instead of CREATE.`;
+}
+
+module.exports = {
+  detectDuplicateStory,
+  suggestRelevantFiles,
+  validateNoDuplicates,
+  // Exposed for testing
+  _formatDuplicateWarning,
+};

package/.aios-core/core/config/schemas/framework-config.schema.json

@@ -5,14 +5,162 @@
   "description": "Read-only framework defaults shipped with the npm package",
   "type": "object",
   "properties": {
-    "version": {
-      "type": "string",
-      "description": "Framework version"
+    "metadata": {
+      "type": "object",
+      "description": "Framework metadata — name and version",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Framework display name"
+        },
+        "framework_version": {
+          "type": "string",
+          "description": "Semantic version of the framework"
+        }
+      },
+      "required": ["name", "framework_version"],
+      "additionalProperties": false
     },
-    "framework_name": {
-      "type": "string",
-      "description": "Framework name"
+    "markdownExploder": {
+      "type": "boolean",
+      "description": "Enable markdown exploder for document processing",
+      "default": true
+    },
+    "resource_locations": {
+      "type": "object",
+      "description": "Default paths for framework resources",
+      "properties": {
+        "agents_dir": { "type": "string", "description": "Path to agent definitions" },
+        "tasks_dir": { "type": "string", "description": "Path to task definitions" },
+        "templates_dir": { "type": "string", "description": "Path to templates" },
+        "checklists_dir": { "type": "string", "description": "Path to checklists" },
+        "tools_dir": { "type": "string", "description": "Path to tools" },
+        "scripts": {
+          "type": "object",
+          "description": "Script directory paths by category",
+          "properties": {
+            "core": { "type": "string" },
+            "development": { "type": "string" },
+            "infrastructure": { "type": "string" },
+            "legacy": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        "data_dir": { "type": "string", "description": "Path to data directory" },
+        "elicitation_dir": { "type": "string", "description": "Path to elicitation templates" },
+        "squads_template_dir": { "type": "string", "description": "Path to squad templates" },
+        "minds_dir": { "type": "string", "description": "Path to minds output" }
+      },
+      "additionalProperties": false
+    },
+    "performance_defaults": {
+      "type": "object",
+      "description": "Default performance tuning options",
+      "properties": {
+        "lazy_loading": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "heavy_sections": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Config sections loaded lazily"
+            }
+          },
+          "additionalProperties": false
+        },
+        "git": {
+          "type": "object",
+          "properties": {
+            "show_config_warning": { "type": "boolean", "default": true },
+            "cache_time_seconds": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "utility_scripts_registry": {
+      "type": "object",
+      "description": "Registry of utility scripts by category",
+      "properties": {
+        "helpers": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Agent helper utility names"
+        },
+        "executors": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Task execution utility names"
+        },
+        "framework": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Framework-level utility names"
+        }
+      },
+      "additionalProperties": false
+    },
+    "ide_sync_system": {
+      "type": "object",
+      "description": "IDE synchronization system for agent definitions",
+      "properties": {
+        "enabled": { "type": "boolean", "default": true },
+        "source": { "type": "string", "description": "Source directory for agent definitions" },
+        "targets": {
+          "type": "object",
+          "description": "IDE target configurations",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "enabled": { "type": "boolean" },
+              "path": { "type": "string" },
+              "format": { "type": "string", "enum": ["full-markdown-yaml", "condensed-rules", "cursor-style"] }
+            },
+            "additionalProperties": false
+          }
+        },
+        "redirects": { "type": "object", "additionalProperties": true },
+        "validation": {
+          "type": "object",
+          "properties": {
+            "strict_mode": { "type": "boolean" },
+            "fail_on_drift": { "type": "boolean" },
+            "fail_on_orphaned": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "template_overrides": {
+      "type": "object",
+      "description": "Template customization defaults (override at L2)",
+      "properties": {
+        "story": {
+          "type": "object",
+          "properties": {
+            "sections_order": {
+              "oneOf": [
+                { "type": "array", "items": { "type": "string" } },
+                { "type": "null" }
+              ],
+              "description": "Custom section order for story templates. null = use template default.",
+              "default": null
+            },
+            "optional_sections": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Section IDs that can be skipped in story templates",
+              "default": []
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }