aios-core 4.2.15 → 4.4.0

package/.aios-core/development/templates/code-intel-integration-pattern.md

@@ -0,0 +1,199 @@
+# Code Intelligence Integration Pattern
+
+> Standard pattern for integrating code intelligence into new tasks and helpers.
+> Follow this template to ensure consistent, provider-agnostic integration with graceful fallback.
+
+## Pattern Overview
+
+```
+import → isCodeIntelAvailable guard → enrich → fallback (return null)
+```
+
+All code intelligence integrations MUST follow this 4-step pattern:
+
+1. **Import** from the code-intel public API (`../index` or relative path)
+2. **Guard** with `isCodeIntelAvailable()` — return null if no provider
+3. **Enrich** by calling enricher/client capabilities inside try/catch
+4. **Fallback** — always return null on any error, never throw
+
+## Complete Example
+
+```javascript
+'use strict';
+
+const { getEnricher, getClient, isCodeIntelAvailable } = require('../index');
+
+/**
+ * ModuleDoc — describe the helper's purpose and target agent/task.
+ *
+ * All functions return null gracefully when no provider is available.
+ * Never throws — safe to call unconditionally in task workflows.
+ */
+
+async function myFunction(param) {
+  // Step 1: Input validation
+  if (!param) return null;
+
+  // Step 2: Provider guard
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    // Step 3: Call enricher (composite) or client (primitive)
+    const enricher = getEnricher();
+    const result = await enricher.someCapability(param);
+
+    // Validate result
+    if (!result) return null;
+
+    // Step 4: Format and return
+    return {
+      // ... formatted result
+    };
+  } catch {
+    // Never throw — return null on any error
+    return null;
+  }
+}
+
+module.exports = { myFunction };
+```
+
+## Partial Results Pattern
+
+When calling multiple capabilities, use per-capability try/catch to accept partial results:
+
+```javascript
+async function multiCapabilityFunction(param) {
+  if (!param) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const enricher = getEnricher();
+    const client = getClient();
+
+    let dataA = null;
+    let dataB = null;
+
+    try {
+      dataA = await enricher.describeProject(param);
+    } catch { /* skip — partial result ok */ }
+
+    try {
+      dataB = await client.findReferences(param);
+    } catch { /* skip — partial result ok */ }
+
+    // Return null only if we got nothing at all
+    if (!dataA && !dataB) return null;
+
+    return { dataA, dataB };
+  } catch {
+    return null;
+  }
+}
+```
+
+## Available Capabilities
+
+### Enricher (composite — via `getEnricher()`)
+
+| Capability | Input | Output | Use Case |
+|-----------|-------|--------|----------|
+| `describeProject(path)` | Path string | `{ codebase, stats }` | Project overview |
+| `getConventions(path)` | Path string | `{ patterns, stats }` | Naming/coding patterns |
+| `detectDuplicates(desc, opts)` | Description + options | `{ matches, codebaseOverview }` | Duplicate detection |
+| `assessImpact(files)` | File array | `{ blastRadius, references, complexity }` | Change impact |
+| `findTests(symbol)` | Symbol name | Test file references | Test discovery |
+
+### Client (primitive — via `getClient()`)
+
+| Capability | Input | Output | Use Case |
+|-----------|-------|--------|----------|
+| `findReferences(symbol)` | Symbol name | `[{ file, line, context }]` | Symbol usage |
+| `findDefinition(symbol)` | Symbol name | `{ file, line, column }` | Symbol definition |
+| `analyzeDependencies(path)` | Path string | `{ nodes, edges }` | Dependency graph |
+| `findCallers(symbol)` | Symbol name | Caller references | Call graph (inbound) |
+| `findCallees(symbol)` | Symbol name | Callee references | Call graph (outbound) |
+| `analyzeComplexity(path)` | Path string | Complexity metrics | Code complexity |
+| `analyzeCodebase(path)` | Path string | Codebase overview | Full analysis |
+| `getProjectStats(path)` | Path string | Project statistics | Stats only |
+
+## Testing Pattern
+
+### Mock Strategy
+
+```javascript
+// Mock the code-intel module at the top of your test file
+jest.mock('../../.aios-core/core/code-intel/index', () => ({
+  isCodeIntelAvailable: jest.fn(),
+  getEnricher: jest.fn(),
+  getClient: jest.fn(),
+}));
+
+const {
+  isCodeIntelAvailable,
+  getEnricher,
+  getClient,
+} = require('../../.aios-core/core/code-intel/index');
+```
+
+### Required Test Scenarios
+
+Every code intelligence integration MUST test:
+
+1. **Happy path** — provider available, data returned
+2. **Fallback** — provider unavailable (`isCodeIntelAvailable` returns false)
+3. **Error handling** — provider throws (enricher/client rejects)
+4. **Empty input** — null/empty parameters
+5. **Partial results** — one capability fails, other succeeds (if multi-capability)
+
+### Test Helper Setup
+
+```javascript
+function setupProviderAvailable() {
+  isCodeIntelAvailable.mockReturnValue(true);
+}
+
+function setupProviderUnavailable() {
+  isCodeIntelAvailable.mockReturnValue(false);
+}
+
+function createMockEnricher(overrides = {}) {
+  const enricher = {
+    detectDuplicates: jest.fn().mockResolvedValue(null),
+    getConventions: jest.fn().mockResolvedValue(null),
+    describeProject: jest.fn().mockResolvedValue(null),
+    assessImpact: jest.fn().mockResolvedValue(null),
+    findTests: jest.fn().mockResolvedValue(null),
+    ...overrides,
+  };
+  getEnricher.mockReturnValue(enricher);
+  return enricher;
+}
+
+function createMockClient(overrides = {}) {
+  const client = {
+    findReferences: jest.fn().mockResolvedValue(null),
+    findDefinition: jest.fn().mockResolvedValue(null),
+    analyzeDependencies: jest.fn().mockResolvedValue(null),
+    // ... add other capabilities as needed
+    ...overrides,
+  };
+  getClient.mockReturnValue(client);
+  return client;
+}
+```
+
+## Existing Helpers (Reference)
+
+| Helper | Agent | Functions | Story |
+|--------|-------|-----------|-------|
+| `dev-helper.js` | @dev | checkBeforeWriting, suggestReuse, getConventionsForPath, assessRefactoringImpact | NOG-3 |
+| `qa-helper.js` | @qa | validateTestCoverage, detectRegressionRisk | NOG-4 |
+| `planning-helper.js` | @architect | analyzeComplexity, suggestArchitecture | NOG-5 |
+| `story-helper.js` | @sm/@po | detectDuplicateStory, suggestRelevantFiles, validateNoDuplicates | NOG-6 |
+| `devops-helper.js` | @devops | assessDeploymentRisk, validatePipelineImpact | NOG-7 |
+| `creation-helper.js` | squad-creator | getCodebaseContext, checkDuplicateArtefact, enrichRegistryEntry | NOG-8 |
+
+---
+
+*Template created for Story NOG-8 — Code Intelligence Integration Pattern*

package/.aios-core/development/templates/ptc-entity-validation.md

@@ -0,0 +1,113 @@
+# PTC Template: Entity Validation Batch
+
+---
+execution_mode: programmatic
+ptc_type: bash-batch  # Fallback — true PTC not available in Claude Code CLI (ADR-7)
+adr_reference: ADR-3 (PTC native ONLY — no MCP tools in batch blocks)
+story: TOK-3
+---
+
+## Purpose
+
+Batch-scan all entities in entity-registry.yaml against their validation rules.
+N entities x M checks consolidated into a single Bash block with one summary output.
+
+**Token savings:** ~20-30% vs individual Grep/Read calls per entity.
+
+## Restriction (ADR-3)
+
+**ONLY native/CLI tools allowed inside this batch block.**
+MCP tools are EXCLUDED. Uses: Bash, grep (via bash), file reads (via bash).
+
+## Template
+
+```bash
+#!/bin/bash
+# PTC-ENTITY-VALIDATION: Batch entity registry scan
+# Usage: Execute as single Bash tool call. Only the final summary enters context.
+
+REGISTRY=".aios-core/data/entity-registry.yaml"
+TOOL_REGISTRY=".aios-core/data/tool-registry.yaml"
+
+PASS=0
+FAIL=0
+WARN=0
+RESULTS=""
+
+# --- Check 1: Registry file exists ---
+if [ ! -f "$REGISTRY" ]; then
+  echo "FATAL: entity-registry.yaml not found at $REGISTRY"
+  exit 1
+fi
+
+# --- Check 2: Required fields present in each entity ---
+required_fields=("name" "type" "layer" "description")
+for field in "${required_fields[@]}"; do
+  count=$(grep -c "  $field:" "$REGISTRY" 2>/dev/null || echo "0")
+  if [ "$count" -gt 0 ]; then
+    RESULTS+="FIELD '$field': found $count occurrences — PASS\n"
+    ((PASS++))
+  else
+    RESULTS+="FIELD '$field': NOT FOUND — FAIL\n"
+    ((FAIL++))
+  fi
+done
+
+# --- Check 3: No duplicate entity names ---
+duplicates=$(grep "^  [a-zA-Z]" "$REGISTRY" | sort | uniq -d)
+if [ -z "$duplicates" ]; then
+  RESULTS+="DUPLICATES: none — PASS\n"
+  ((PASS++))
+else
+  RESULTS+="DUPLICATES: found\n$duplicates\n— FAIL\n"
+  ((FAIL++))
+fi
+
+# --- Check 4: Tool registry consistency ---
+if [ -f "$TOOL_REGISTRY" ]; then
+  tool_count=$(grep -c "tier:" "$TOOL_REGISTRY" 2>/dev/null || echo "0")
+  RESULTS+="TOOL-REGISTRY: $tool_count tools found — PASS\n"
+  ((PASS++))
+else
+  RESULTS+="TOOL-REGISTRY: file missing — WARN\n"
+  ((WARN++))
+fi
+
+# --- Check 5: Layer annotations valid (L1-L4) ---
+invalid_layers=$(grep "layer:" "$REGISTRY" | grep -v "L[1-4]" | head -5)
+if [ -z "$invalid_layers" ]; then
+  RESULTS+="LAYERS: all valid (L1-L4) — PASS\n"
+  ((PASS++))
+else
+  RESULTS+="LAYERS: invalid entries found\n$invalid_layers\n— FAIL\n"
+  ((FAIL++))
+fi
+
+# --- Summary ---
+echo "=== ENTITY VALIDATION SUMMARY ==="
+echo "Passed: $PASS | Failed: $FAIL | Warnings: $WARN"
+echo ""
+echo -e "$RESULTS"
+
+if [ $FAIL -gt 0 ]; then
+  echo "VERDICT: FAIL"
+  exit 1
+else
+  echo "VERDICT: PASS"
+  exit 0
+fi
+```
+
+## Token Comparison
+
+| Approach | Tool Calls | Context Entries | Estimated Tokens |
+|----------|-----------|-----------------|-----------------|
+| Direct (N checks) | 5-10 | 5-10 (each result) | ~5,000-10,000 |
+| Batch (1 call) | 1 | 1 (summary only) | ~2,000-3,000 |
+| **Reduction** | -80% calls | -80% entries | **~20-40%** |
+
+## Notes
+
+- Extensible: add more checks by appending to the script
+- Each check reports PASS/FAIL/WARN independently
+- Only summary enters context — intermediate grep/read results stay in shell

package/.aios-core/development/templates/ptc-qa-gate.md

@@ -0,0 +1,100 @@
+# PTC Template: QA Gate Batch
+
+---
+execution_mode: programmatic
+ptc_type: bash-batch  # Fallback — true PTC not available in Claude Code CLI (ADR-7)
+adr_reference: ADR-3 (PTC native ONLY — no MCP tools in batch blocks)
+story: TOK-3
+---
+
+## Purpose
+
+Consolidate QA Gate checks (lint, typecheck, test) into a single Bash block.
+Intermediate results stay in shell variables — only the final summary enters context.
+
+**Token savings:** ~20% vs 3 separate tool calls (conservative estimate).
+True PTC (API-level) would yield ~37% but is not available in Claude Code CLI.
+
+## Restriction (ADR-3)
+
+**ONLY native/CLI tools allowed inside this batch block.**
+MCP tools (EXA, Playwright, Apify, Context7, Nogic, Code-Graph) are EXCLUDED.
+
+Eligible tools: Bash, Read, Write, Edit, Grep, Glob (all `ptc_eligible: true` in tool-registry.yaml).
+
+## Template
+
+```bash
+#!/bin/bash
+# PTC-QA-GATE: Batch quality checks — single Bash block, one summary output
+# Usage: Execute as single Bash tool call. Only the final echo enters context.
+
+set -o pipefail
+
+PASS=0
+FAIL=0
+RESULTS=""
+
+# --- Check 1: Lint ---
+lint_output=$(npm run lint 2>&1)
+lint_exit=$?
+if [ $lint_exit -eq 0 ]; then
+  RESULTS+="LINT: PASS\n"
+  ((PASS++))
+else
+  RESULTS+="LINT: FAIL\n${lint_output}\n"
+  ((FAIL++))
+fi
+
+# --- Check 2: TypeCheck ---
+typecheck_output=$(npm run typecheck 2>&1)
+typecheck_exit=$?
+if [ $typecheck_exit -eq 0 ]; then
+  RESULTS+="TYPECHECK: PASS\n"
+  ((PASS++))
+else
+  RESULTS+="TYPECHECK: FAIL\n${typecheck_output}\n"
+  ((FAIL++))
+fi
+
+# --- Check 3: Tests ---
+test_output=$(npm test 2>&1)
+test_exit=$?
+if [ $test_exit -eq 0 ]; then
+  RESULTS+="TESTS: PASS\n"
+  ((PASS++))
+else
+  RESULTS+="TESTS: FAIL\n${test_output}\n"
+  ((FAIL++))
+fi
+
+# --- Summary (only this enters context) ---
+echo "=== QA GATE SUMMARY ==="
+echo "Passed: $PASS / $((PASS + FAIL))"
+echo "Failed: $FAIL"
+echo ""
+echo -e "$RESULTS"
+
+if [ $FAIL -gt 0 ]; then
+  echo "VERDICT: FAIL"
+  exit 1
+else
+  echo "VERDICT: PASS"
+  exit 0
+fi
+```
+
+## Token Comparison
+
+| Approach | Tool Calls | Context Entries | Estimated Tokens |
+|----------|-----------|-----------------|-----------------|
+| Direct (3 calls) | 3 | 3 (each result) | ~3,000-9,000 |
+| Batch (1 call) | 1 | 1 (summary only) | ~1,500-3,000 |
+| **Reduction** | -67% calls | -67% entries | **~20-50%** |
+
+## Notes
+
+- If any check fails, the full output for that check is included in summary
+- Passing checks show only "PASS" (minimal context)
+- Exit code 1 = at least one check failed
+- This template can be extended with additional checks (build, coverage, etc.)

package/.aios-core/development/templates/ptc-research-aggregation.md

@@ -0,0 +1,94 @@
+# PTC Template: Research Aggregation Batch
+
+---
+execution_mode: programmatic
+ptc_type: bash-batch  # Fallback — true PTC not available in Claude Code CLI (ADR-7)
+adr_reference: ADR-3 (PTC native ONLY — no MCP tools in batch blocks)
+story: TOK-3
+---
+
+## Purpose
+
+Consolidate multi-file research aggregation (scan docs, extract findings, merge)
+into a single Bash block. Intermediate grep/read results stay in shell variables.
+
+**Token savings:** ~20% vs multiple Read + Grep tool calls.
+
+**Note:** This template uses native CLI tools only. For web-based research
+(WebSearch, EXA), those tool calls must remain separate — they are NOT
+ptc_eligible (MCP tools excluded per ADR-3). This template covers the
+**aggregation** phase (local file scanning), not the **search** phase.
+
+## Restriction (ADR-3)
+
+**ONLY native/CLI tools allowed inside this batch block.**
+MCP tools (EXA, Context7, Apify) are EXCLUDED from batch blocks.
+WebSearch/WebFetch are native Tier 1 but operate as API calls — they can be
+included in batch if executed via shell scripting patterns.
+
+## Template
+
+```bash
+#!/bin/bash
+# PTC-RESEARCH-AGGREGATION: Batch scan research docs and aggregate findings
+# Usage: Execute as single Bash tool call. Only the final summary enters context.
+
+RESEARCH_DIR="docs/research"
+OUTPUT=""
+TOPICS_FOUND=0
+FILES_SCANNED=0
+
+# --- Scan all research directories ---
+for dir in "$RESEARCH_DIR"/*/; do
+  if [ -d "$dir" ]; then
+    readme="$dir/README.md"
+    if [ -f "$readme" ]; then
+      ((FILES_SCANNED++))
+
+      # Extract title (first H1)
+      title=$(grep -m1 "^# " "$readme" | sed 's/^# //')
+
+      # Extract key findings (lines with "finding" or "conclusion" or "result")
+      findings=$(grep -i -c "finding\|conclusion\|result\|recommendation" "$readme" 2>/dev/null || echo "0")
+
+      # Extract token/performance metrics if present
+      metrics=$(grep -i "token\|reduction\|saving\|performance\|latency" "$readme" | head -3)
+
+      OUTPUT+="## $title\n"
+      OUTPUT+="- Source: $readme\n"
+      OUTPUT+="- Key findings count: $findings\n"
+      if [ -n "$metrics" ]; then
+        OUTPUT+="- Metrics:\n"
+        while IFS= read -r line; do
+          OUTPUT+="  - $line\n"
+        done <<< "$metrics"
+      fi
+      OUTPUT+="\n"
+      ((TOPICS_FOUND++))
+    fi
+  fi
+done
+
+# --- Summary ---
+echo "=== RESEARCH AGGREGATION SUMMARY ==="
+echo "Directories scanned: $FILES_SCANNED"
+echo "Topics with findings: $TOPICS_FOUND"
+echo ""
+echo -e "$OUTPUT"
+```
+
+## Token Comparison
+
+| Approach | Tool Calls | Context Entries | Estimated Tokens |
+|----------|-----------|-----------------|-----------------|
+| Direct (N reads + N greps) | 10-20 | 10-20 results | ~8,000-15,000 |
+| Batch (1 call) | 1 | 1 (summary only) | ~3,000-5,000 |
+| **Reduction** | -90% calls | -90% entries | **~30-50%** |
+
+## Notes
+
+- Scans `docs/research/*/README.md` by default — adjust path as needed
+- Extracts title, findings count, and performance metrics per research doc
+- Only the aggregated summary enters context
+- For web research (EXA, WebSearch), run those as separate tool calls first,
+  then use this template to aggregate the saved results