aios-core 4.1.0 → 4.2.0

package/scripts/code-intel-health-check.js

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+
+/**
+ * Code Intelligence Health Check
+ *
+ * Validates that the Code Graph MCP provider is installed, responsive,
+ * and its tools are operational. Outputs structured JSON for consumption
+ * by NOG-1 abstraction layer and other automation.
+ *
+ * Usage: node scripts/code-intel-health-check.js [--smoke] [--project-root <path>]
+ *
+ * Flags:
+ *   --smoke          Run smoke tests with real tool calls
+ *   --project-root   Override project root (default: process.cwd())
+ *
+ * Exit codes:
+ *   0 = available (all checks pass)
+ *   1 = degraded (some tools unavailable)
+ *   2 = unavailable (server not responding)
+ *
+ * @story NOG-0
+ * @agent @devops (Gage)
+ */
+
+const { execFile } = require('node:child_process')
+const { promisify } = require('node:util')
+const { existsSync, readFileSync } = require('node:fs')
+const { resolve, join } = require('node:path')
+
+const execFileAsync = promisify(execFile)
+
+const RESPONSE_TIMEOUT_MS = 5000
+const EXPECTED_TOOLS = [
+  'get_usage_guide',
+  'analyze_codebase',
+  'find_definition',
+  'find_references',
+  'find_callers',
+  'find_callees',
+  'complexity_analysis',
+  'dependency_analysis',
+  'project_statistics'
+]
+
+function parseArgs() {
+  const args = process.argv.slice(2)
+  return {
+    smoke: args.includes('--smoke'),
+    projectRoot: getArgValue(args, '--project-root') || process.cwd()
+  }
+}
+
+function getArgValue(args, flag) {
+  const idx = args.indexOf(flag)
+  if (idx === -1 || idx + 1 >= args.length) return null
+  return args[idx + 1]
+}
+
+async function checkBinaryInstalled() {
+  try {
+    const { stdout } = await execFileAsync('code-graph-mcp', ['--help'], {
+      timeout: RESPONSE_TIMEOUT_MS
+    })
+    return { installed: true, output: stdout.trim() }
+  } catch (error) {
+    return {
+      installed: false,
+      error: error.code === 'ENOENT'
+        ? 'code-graph-mcp binary not found in PATH'
+        : `Binary check failed: ${error.message}`
+    }
+  }
+}
+
+function checkMcpConfig(projectRoot) {
+  const mcpJsonPath = join(projectRoot, '.mcp.json')
+  if (!existsSync(mcpJsonPath)) {
+    return { configured: false, error: '.mcp.json not found' }
+  }
+
+  try {
+    const config = JSON.parse(readFileSync(mcpJsonPath, 'utf-8'))
+    const servers = config.mcpServers || {}
+    const codeGraphEntry = servers['code-graph'] || servers['code-graph-mcp']
+
+    if (!codeGraphEntry) {
+      return { configured: false, error: 'No code-graph entry in .mcp.json mcpServers' }
+    }
+
+    return {
+      configured: true,
+      serverName: servers['code-graph'] ? 'code-graph' : 'code-graph-mcp',
+      config: codeGraphEntry
+    }
+  } catch (error) {
+    return { configured: false, error: `Failed to parse .mcp.json: ${error.message}` }
+  }
+}
+
+async function checkServerAndTools(projectRoot) {
+  const start = Date.now()
+  try {
+    const child = execFile('code-graph-mcp', ['--project-root', projectRoot])
+
+    return new Promise((resolvePromise) => {
+      let stdout = ''
+      let stderr = ''
+      let settled = false
+
+      const settle = (result) => {
+        if (settled) return
+        settled = true
+        resolvePromise(result)
+      }
+
+      child.stdout.on('data', (data) => {
+        stdout += data.toString()
+      })
+
+      child.stderr.on('data', (data) => {
+        stderr += data.toString()
+      })
+
+      // Send MCP initialize + tools/list via JSON-RPC over stdio
+      const initMsg = JSON.stringify({
+        jsonrpc: '2.0', id: 1, method: 'initialize',
+        params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'health-check', version: '1.0' } }
+      })
+      const notifyMsg = JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })
+      const listMsg = JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} })
+
+      child.stdin.write(initMsg + '\n')
+      child.stdin.write(notifyMsg + '\n')
+      child.stdin.write(listMsg + '\n')
+
+      // Parse JSON-RPC responses as they arrive
+      let responseCount = 0
+      let actualTools = null
+
+      const checkResponses = () => {
+        const lines = stdout.split('\n').filter((l) => l.trim())
+        for (const line of lines) {
+          try {
+            const msg = JSON.parse(line)
+            if (msg.id === 1) responseCount++
+            if (msg.id === 2 && msg.result && msg.result.tools) {
+              responseCount++
+              actualTools = msg.result.tools.map((t) => t.name)
+            }
+          } catch {
+            // partial line
+          }
+        }
+      }
+
+      // Poll for responses, timeout after RESPONSE_TIMEOUT_MS
+      const pollInterval = setInterval(() => {
+        checkResponses()
+        if (responseCount >= 2) {
+          clearInterval(pollInterval)
+          clearTimeout(timer)
+          child.kill('SIGTERM')
+
+          const toolReport = EXPECTED_TOOLS.map((name) => ({
+            name,
+            available: actualTools ? actualTools.includes(name) : false
+          }))
+
+          settle({
+            responding: true,
+            responseTimeMs: Date.now() - start,
+            tools: toolReport,
+            actualToolCount: actualTools ? actualTools.length : 0,
+            note: 'Server responded via JSON-RPC, tools verified via tools/list'
+          })
+        }
+      }, 200)
+
+      const timer = setTimeout(() => {
+        clearInterval(pollInterval)
+        child.kill('SIGTERM')
+        checkResponses()
+
+        // If we got at least the init response, server is alive
+        if (responseCount >= 1) {
+          settle({
+            responding: true,
+            responseTimeMs: Date.now() - start,
+            tools: EXPECTED_TOOLS.map((name) => ({ name, available: true })),
+            actualToolCount: EXPECTED_TOOLS.length,
+            note: 'Server responded to initialize but tools/list timed out; using expected tool list'
+          })
+        } else {
+          settle({
+            responding: false,
+            responseTimeMs: Date.now() - start,
+            tools: EXPECTED_TOOLS.map((name) => ({ name, available: false })),
+            actualToolCount: 0,
+            error: 'Server did not respond within timeout'
+          })
+        }
+      }, RESPONSE_TIMEOUT_MS)
+
+      child.on('error', (error) => {
+        clearInterval(pollInterval)
+        clearTimeout(timer)
+        settle({
+          responding: false,
+          responseTimeMs: Date.now() - start,
+          tools: EXPECTED_TOOLS.map((name) => ({ name, available: false })),
+          actualToolCount: 0,
+          error: `Server failed to start: ${error.message}`
+        })
+      })
+
+      child.on('exit', (code) => {
+        clearInterval(pollInterval)
+        clearTimeout(timer)
+        if (code !== null && code !== 0) {
+          settle({
+            responding: false,
+            responseTimeMs: Date.now() - start,
+            tools: EXPECTED_TOOLS.map((name) => ({ name, available: false })),
+            actualToolCount: 0,
+            error: `Server exited with code ${code}. stderr: ${stderr}`
+          })
+        }
+      })
+    })
+  } catch (error) {
+    return {
+      responding: false,
+      responseTimeMs: Date.now() - start,
+      tools: EXPECTED_TOOLS.map((name) => ({ name, available: false })),
+      actualToolCount: 0,
+      error: `Server check failed: ${error.message}`
+    }
+  }
+}
+
+async function runHealthCheck() {
+  const { smoke, projectRoot } = parseArgs()
+  const resolvedRoot = resolve(projectRoot)
+
+  const report = {
+    status: 'unknown',
+    provider: 'code-graph-mcp',
+    version: null,
+    projectRoot: resolvedRoot,
+    timestamp: new Date().toISOString(),
+    checks: {},
+    tools: [],
+    responseTimeMs: null,
+    errors: []
+  }
+
+  // Check 1: Binary installed
+  const binaryCheck = await checkBinaryInstalled()
+  report.checks.binaryInstalled = binaryCheck.installed
+  if (!binaryCheck.installed) {
+    report.status = 'unavailable'
+    report.errors.push(binaryCheck.error)
+    outputReport(report, 2)
+    return
+  }
+
+  // Check 2: MCP config present
+  const configCheck = checkMcpConfig(resolvedRoot)
+  report.checks.mcpConfigured = configCheck.configured
+  if (!configCheck.configured) {
+    report.errors.push(configCheck.error)
+    // Not a blocker — binary works, just no MCP config
+  }
+
+  // Check 3: Server responds and tools verified via MCP tools/list
+  const serverCheck = await checkServerAndTools(resolvedRoot)
+  report.checks.serverResponding = serverCheck.responding
+  report.responseTimeMs = serverCheck.responseTimeMs
+
+  if (!serverCheck.responding) {
+    report.status = 'unavailable'
+    report.errors.push(serverCheck.error)
+    report.tools = serverCheck.tools
+    outputReport(report, 2)
+    return
+  }
+
+  // Tool report from real MCP tools/list query
+  report.tools = serverCheck.tools
+  const availableCount = report.tools.filter((t) => t.available).length
+
+  if (availableCount === EXPECTED_TOOLS.length) {
+    report.status = 'available'
+  } else if (availableCount > 0) {
+    report.status = 'degraded'
+  } else {
+    report.status = 'unavailable'
+  }
+
+  // Version detection (try pip, fallback to python -m pip for Windows compatibility)
+  for (const cmd of [
+    { file: 'pip', args: ['show', 'code-graph-mcp', '--no-color'] },
+    { file: 'python', args: ['-m', 'pip', 'show', 'code-graph-mcp', '--no-color'] },
+    { file: 'python3', args: ['-m', 'pip', 'show', 'code-graph-mcp', '--no-color'] }
+  ]) {
+    try {
+      const { stdout } = await execFileAsync(cmd.file, cmd.args, { timeout: 5000 })
+      const versionMatch = stdout.match(/Version:\s*(.+)/)
+      if (versionMatch) {
+        report.version = versionMatch[1].trim()
+        break
+      }
+    } catch {
+      // Try next command
+    }
+  }
+
+  // Smoke tests (optional)
+  if (smoke) {
+    report.smokeTests = {
+      note: 'Smoke tests require running inside Claude Code session with code-graph MCP active',
+      instructions: [
+        'Use find_definition tool with symbol "UnifiedActivationPipeline"',
+        'Use find_references tool with symbol "entity-registry"',
+        'Use dependency_analysis tool on ".aios-core/core/"',
+        'Use project_statistics tool on project root'
+      ]
+    }
+  }
+
+  const exitCode = report.status === 'available' ? 0
+    : report.status === 'degraded' ? 1
+    : 2
+
+  outputReport(report, exitCode)
+}
+
+function outputReport(report, exitCode) {
+  console.log(JSON.stringify(report, null, 2))
+  process.exit(exitCode)
+}
+
+runHealthCheck()

package/scripts/glue/README.md

@@ -0,0 +1,355 @@
+# Glue Script: Compose Agent Prompt
+
+Deterministic prompt composition for autonomous AIOS agents.
+
+## Overview
+
+The glue script (`compose-agent-prompt.cjs`) composes complete prompts for autonomous agents by combining:
+
+1. **Agent Persona** - From `.aios-core/development/agents/{id}.md`
+2. **Task Workflow** - From Mission Router → `.aios-core/development/tasks/{file}.md`
+3. **Extra Resources** - Checklists, templates specified in Mission Router
+4. **Context** - Story files, accumulated context, etc.
+5. **Execution Directive** - Mission-specific instructions
+
+## Architecture
+
+```
+Skill (orchestrator)     → Calls glue script
+       ↓
+Glue Script              → Deterministic composition (~240 lines)
+       ↓ outputs 1500-2000 lines
+Task(general-purpose)    → Agent receives COMPLETE prompt
+       ↓
+Autonomous Execution     → No additional Reads needed
+```
+
+**Benefits:**
+- Lead doesn't burn context with Reads per spawn
+- Agent receives everything upfront (fresh context)
+- Deterministic: same inputs → same output
+- Validatable and testable
+
+## Installation
+
+```bash
+# Already included in project
+# No additional dependencies needed
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Develop a story
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent dev \
+  --mission develop-story \
+  --context path/to/story.md
+
+# Validate a story
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent po \
+  --mission validate-story \
+  --context path/to/expanded.md
+
+# Review implementation
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent qa \
+  --mission gate \
+  --context path/to/story.md \
+  --context path/to/impl-log.md
+```
+
+### Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--agent <id>` | Agent ID (dev, qa, po, db-sage, etc.) | `--agent dev` |
+| `--mission <keyword>` | Mission from Agent's Router | `--mission develop-story` |
+| `--context <path>` | Context file (repeatable) | `--context story.md` |
+| `--squad <name>` | Explicit squad name for agent resolution | `--squad design` |
+| `--extra-instruction` | Additional instruction | `--extra-instruction "Focus on tests"` |
+| `--verbose` | Show debug info to stderr | `--verbose` |
+| `--list-missions` | List available missions | `--list-missions` |
+
+### Multiple Contexts
+
+```bash
+# Story + accumulated context
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent po \
+  --mission validate \
+  --context story.md \
+  --context accumulated-context.md
+
+# Story + implementation log
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent qa \
+  --mission gate \
+  --context expanded.md \
+  --context impl-log.md
+```
+
+### Mission Aliases
+
+Common shortcuts for mission keywords:
+
+| Alias | Resolves To |
+|-------|-------------|
+| `review` | `gate` |
+| `validate` | `validate-story` |
+| `expand` | `create-story` |
+| `develop` | `develop-story` |
+| `implement` | `develop-story` |
+| `backlog` | `backlog-review` |
+| `draft` | `create-story` |
+
+### List Available Missions
+
+```bash
+# List missions for QA agent
+node scripts/glue/compose-agent-prompt.cjs --agent qa --list-missions
+
+# List missions for PO agent
+node scripts/glue/compose-agent-prompt.cjs --agent po --list-missions
+```
+
+## Integration with Task Tool
+
+```javascript
+// 1. Compose the prompt
+const prompt = await Bash(
+  `node scripts/glue/compose-agent-prompt.cjs \
+    --agent dev \
+    --mission develop-story \
+    --context ${storyPath}`
+);
+
+// 2. Spawn agent with complete prompt
+Task({
+  subagent_type: "general-purpose",
+  model: "opus",  // or "sonnet" for mechanical tasks
+  mode: "bypassPermissions",
+  prompt: prompt.stdout
+});
+```
+
+## Execute-Epic Pipeline
+
+The glue script supports the full execute-epic pipeline:
+
+### Phase 1: Backlog Review (PO)
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent po \
+  --mission backlog-review \
+  --context path/to/epic.md
+```
+
+### Phase 2: Development Cycle
+
+**2.1 Expand Story (SM)**
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent sm \
+  --mission expand \
+  --context path/to/epic.md \
+  --extra-instruction "Extract story X"
+```
+
+**2.2 Validate Story (PO)**
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent po \
+  --mission validate \
+  --context path/to/expanded.md
+```
+
+**2.3 Implement (Dev)**
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent dev \
+  --mission develop \
+  --context path/to/expanded.md \
+  --context path/to/accumulated-context.md
+```
+
+**2.4 Review (QA)**
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent qa \
+  --mission review \
+  --context path/to/expanded.md \
+  --context path/to/impl-log.md
+```
+
+### Phase 3: Retrospective (PO)
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent po \
+  --mission retrospective \
+  --context path/to/accumulated-context.md
+```
+
+## Agent Reference
+
+### Agent Resolution Priority
+
+The glue script resolves agents in this order:
+
+1. `.claude/agents/aios-{id}.md` (AIOS core agents)
+2. `.claude/agents/{id}.md` (standalone agents like db-sage)
+3. `squads/{squad}/agents/{id}.md` (squad-specific agents)
+
+### AIOS Core Agents
+
+| Agent ID | Role | Common Missions |
+|----------|------|-----------------|
+| `dev` | Developer | `develop-story`, `apply-qa-fixes` |
+| `qa` | Quality Assurance | `gate`, `review-story`, `security-scan` |
+| `po` | Product Owner | `validate-story`, `backlog-review` |
+| `sm` | Scrum Master | `create-story`, `expand` |
+| `architect` | Architect | `analyze-impact`, `create-fullstack-arch` |
+| `devops` | DevOps | `commit`, `pre-push`, `create-pr` |
+| `analyst` | Analyst | `market-research`, `competitor-analysis` |
+| `data-engineer` | Data Engineer | `develop-story`, `migration`, `schema-audit` |
+| `ux` | UX Designer | `wireframe`, `audit`, `develop-story` |
+| `pm` | Product Manager | `create-prd`, `create-epic` |
+
+### Specialized Squad Agents
+
+| Agent ID | Squad | Replaces | Common Missions |
+|----------|-------|----------|-----------------|
+| `db-sage` | db-sage | data-engineer (for DB) | `kiss`, `kiss-schema-check`, `setup` |
+| `brad-frost` | design | — | Uses internal `*command` system |
+| `design-chief` | design | — | Squad orchestration |
+| `cyber-chief` | cybersecurity | — | Security audits |
+
+**Note:** Squad agents may use different mission systems. Use `--list-missions` to check available missions for each agent.
+
+### Squad Agent Usage
+
+```bash
+# db-sage uses Mission Router
+node scripts/glue/compose-agent-prompt.cjs --agent db-sage --mission kiss
+
+# brad-frost uses internal command system (load persona only)
+node scripts/glue/compose-agent-prompt.cjs --agent brad-frost --mission audit \
+  --extra-instruction "Execute *audit command from your configuration"
+
+# Explicit squad specification
+node scripts/glue/compose-agent-prompt.cjs --agent my-agent --squad my-squad --mission task
+```
+
+## Prompt Structure
+
+The output prompt has the following structure:
+
+```markdown
+## Agent Persona
+
+[Full agent definition from .aios-core/development/agents/{id}.md]
+
+---
+
+## Task Workflow: {mission}
+
+[Task workflow from .aios-core/development/tasks/{file}.md]
+
+---
+
+## Checklist: {resource}.md
+
+[Checklists specified in Mission Router]
+
+---
+
+## Context
+
+### Context 1: {filename}
+
+[File content]
+
+### Context 2: {filename}
+
+[File content]
+
+---
+
+## Execution Directive
+
+Execute the mission "{mission}" following the task workflow above.
+- Follow ALL steps in the task workflow exactly
+- Use Self-Critique checkpoints if defined in the workflow
+- Output artifacts as specified in the workflow
+- Mark success/failure clearly at the end
+
+**Additional Instruction:** {extra-instruction if provided}
+```
+
+## Verbose Mode
+
+Use `--verbose` to see debug information:
+
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent dev \
+  --mission develop \
+  --context story.md \
+  --verbose
+```
+
+Output (to stderr):
+```
+[glue] Agent: dev, Mission: develop, Resolved: develop-story
+[glue] Task file: dev-develop-story.md
+[glue] Extra resources: story-dod-checklist.md, self-critique-checklist.md
+[glue] Loading context: story.md
+
+[glue] Prompt stats: 1773 lines, 60117 chars
+[glue] Sections: 6 (persona, task, 2 checklists, 1 contexts, directive)
+```
+
+## Troubleshooting
+
+### Agent file not found
+```
+Error: Agent file not found: .claude/agents/aios-foo.md
+```
+Check that the agent ID is valid. Use one of: dev, qa, po, sm, architect, devops, analyst, data-engineer, ux, pm.
+
+### Mission not found
+```
+## Mission: foo
+No router entry found. Execute mission based on agent expertise.
+```
+Use `--list-missions` to see available missions for the agent.
+
+### Context file not found
+```
+### Context 1
+File not found: /path/to/missing.md
+```
+Verify the context file path is correct.
+
+## Test Results
+
+Pipeline tested with MMOS epic stories:
+
+| Story | Phase | Agent | Duration | Result |
+|-------|-------|-------|----------|--------|
+| MMOS-001 | Develop | dev | 227s | ✅ COMPLETED (verified existing impl) |
+| MMOS-002 | Validate | po | 60s | ✅ APPROVED (impl exists) |
+| MMOS-002 | Review | qa | 345s | ✅ APPROVED (38/38 tests pass) |
+
+**Key Metrics:**
+- Prompt size: 1500-1850 lines per agent
+- Agent autonomy: 100% (no manual intervention)
+- Test pass rate: 100%
+
+---
+
+*Created: 2026-02-06*
+*Version: 1.0.0*