mia-code 0.2.0 → 0.3.0

package/rispecs/living-specifications.rispecs.md

@@ -0,0 +1,361 @@
+# Living Specifications Engine (RispecsEngine)
+
+> RISE Framework Specification v1.0
+> Document: mia-code/rispecs/living-specifications.rispecs.md
+> Status: mia-code Enhancement
+
+---
+
+## Creative Intent
+
+The RispecsEngine empowers developers to create specifications that evolve with the codebase. Users achieve "living documentation" where rispecs files automatically update from git history, maintaining structural accuracy as code changes without manual synchronization effort.
+
+---
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- mia-code has 7 rispecs files defining behavior (`core.rispecs.md`, `engines.rispecs.md`, etc.)
+- Specifications are manually written and updated
+- Git commit messages contain valuable specification-relevant information (e.g., `feat(memory): Operationalize Structural Dynamics`)
+- No automated connection between code changes and specification updates
+- Documentation drift occurs as implementation evolves
+- Existing specs: `core.rispecs.md`, `engines.rispecs.md`, `formatting.rispecs.md`, `pde.rispecs.md`, `session.rispecs.md`, `unifier.rispecs.md`
+
+**Desired Structural State:**
+- RispecsEngine watches git commits affecting spec-related files
+- Conventional commits automatically suggest spec updates
+- Breaking changes trigger mandatory spec review
+- Spec sections reference source files with auto-refresh
+- Change log generated from git history integrated into specs
+- LLM-assisted spec refinement based on implementation diffs
+
+---
+
+## Core Components
+
+### RispecsEngine
+
+**Purpose:** Orchestrate living specification lifecycle.
+
+```typescript
+interface RispecsEngine {
+  // Initialization
+  init(projectRoot: string): Promise<void>;
+  
+  // Watching
+  watchGitCommits(options: WatchOptions): void;
+  
+  // Analysis
+  analyzeCommit(commit: GitCommit): SpecImpact[];
+  suggestSpecUpdates(impacts: SpecImpact[]): SpecUpdate[];
+  
+  // Updating
+  applyUpdate(update: SpecUpdate, mode: 'auto' | 'interactive'): Promise<void>;
+  
+  // Validation
+  validateSpecCoverage(): CoverageReport;
+  detectDrift(): DriftReport;
+  
+  // Generation
+  generateChangeLog(since: string): string;
+  refreshSourceReferences(): Promise<void>;
+}
+
+interface WatchOptions {
+  branches: string[];          // e.g., ['main', 'develop']
+  filePatterns: string[];      // e.g., ['src/**/*.ts']
+  specDirectory: string;       // e.g., 'rispecs'
+  autoUpdate: boolean;
+}
+
+interface SpecImpact {
+  commit: GitCommit;
+  affectedSpecs: string[];     // Spec file paths
+  impactType: 'additive' | 'modifying' | 'breaking';
+  suggestedSections: string[]; // Sections to update
+  confidence: number;          // 0-1
+}
+
+interface SpecUpdate {
+  specFile: string;
+  section: string;
+  currentContent: string;
+  proposedContent: string;
+  reason: string;
+  sourceCommits: string[];     // SHA references
+}
+```
+
+### ConventionalCommitParser
+
+**Purpose:** Extract specification-relevant information from commits.
+
+```typescript
+interface ConventionalCommitParser {
+  parse(commitMessage: string): ParsedCommit;
+  
+  mapToSpecImpact(parsed: ParsedCommit, diff: GitDiff): SpecImpact;
+}
+
+interface ParsedCommit {
+  type: 'feat' | 'fix' | 'refactor' | 'docs' | 'chore' | 'breaking';
+  scope?: string;              // e.g., 'memory', 'engines', 'session'
+  description: string;
+  body?: string;
+  footers?: Record<string, string>;
+  breaking: boolean;
+}
+
+// Mapping conventional commit scopes to spec files
+const SCOPE_TO_SPEC: Record<string, string> = {
+  'memory': 'session.rispecs.md',
+  'engines': 'engines.rispecs.md',
+  'unifier': 'unifier.rispecs.md',
+  'formatting': 'formatting.rispecs.md',
+  'cli': 'core.rispecs.md',
+  'config': 'core.rispecs.md',
+};
+```
+
+### SourceReferenceManager
+
+**Purpose:** Maintain links between spec sections and source files.
+
+```typescript
+interface SourceReferenceManager {
+  // Extract references from spec markdown
+  parseReferences(specContent: string): SourceReference[];
+  
+  // Validate references still exist
+  validateReferences(refs: SourceReference[]): ValidationResult;
+  
+  // Update line numbers after code changes
+  refreshLineNumbers(refs: SourceReference[], diff: GitDiff): SourceReference[];
+  
+  // Inject fresh code snippets
+  refreshCodeBlocks(specContent: string): string;
+}
+
+interface SourceReference {
+  specFile: string;
+  specSection: string;
+  sourceFile: string;
+  lineRange?: [number, number];
+  symbol?: string;             // e.g., 'runGeminiHeadless'
+  type: 'implementation' | 'interface' | 'example';
+}
+```
+
+### DriftDetector
+
+**Purpose:** Identify when specifications diverge from implementation.
+
+```typescript
+interface DriftDetector {
+  // Compare spec assertions to actual code
+  detectDrift(specFile: string): DriftReport;
+  
+  // Batch check all specs
+  fullScan(): DriftReport[];
+}
+
+interface DriftReport {
+  specFile: string;
+  driftItems: DriftItem[];
+  overallHealth: 'healthy' | 'warning' | 'critical';
+  lastValidated: string;
+}
+
+interface DriftItem {
+  section: string;
+  claim: string;               // What the spec says
+  reality: string;             // What the code does
+  severity: 'minor' | 'moderate' | 'major';
+  suggestedAction: 'update_spec' | 'update_code' | 'investigate';
+}
+```
+
+---
+
+## Integration with mia-code
+
+### Workflow Integration
+
+```typescript
+// In mia-code CLI
+import { RispecsEngine } from './rispecs/engine';
+
+// Post-session hook
+async function onSessionEnd(sessionSummary: SessionSummary) {
+  const engine = new RispecsEngine();
+  
+  // Check for spec-relevant changes
+  const recentCommits = await git.log({ since: session.startedAt });
+  const impacts = recentCommits.map(c => engine.analyzeCommit(c)).flat();
+  
+  if (impacts.length > 0) {
+    const updates = engine.suggestSpecUpdates(impacts);
+    
+    // Present to user via Miette interpretation
+    console.log('🌸 miette: These specifications may need attention:');
+    for (const update of updates) {
+      console.log(`  - ${update.specFile} / ${update.section}`);
+      console.log(`    Reason: ${update.reason}`);
+    }
+  }
+}
+```
+
+### Ceremonial Integration
+
+```typescript
+// Log spec updates as ceremonies
+const ceremony: Ceremony = {
+  type: 'spec_updated',
+  participants: ['rispec_engine', 'developer'],
+  intentions: ['Maintain living documentation'],
+  observations: [
+    `Updated ${update.specFile} section "${update.section}"`,
+    `Based on commits: ${update.sourceCommits.join(', ')}`
+  ],
+  timestamp: new Date().toISOString()
+};
+```
+
+### Git Hooks Integration
+
+```bash
+# .git/hooks/post-commit
+#!/bin/bash
+npx mia-code rispecs check-drift --quiet
+if [ $? -ne 0 ]; then
+  echo "⚠️  Specification drift detected. Run 'mia-code rispecs validate' for details."
+fi
+```
+
+---
+
+## Spec File Enhancements
+
+### Source Reference Syntax
+
+```markdown
+<!-- In rispecs file -->
+
+## Implementation Reference
+
+<!-- @source-ref: src/geminiHeadless.ts#runGeminiHeadless -->
+```typescript
+export async function runGeminiHeadless(
+  prompt: string,
+  config: MiaCodeConfig,
+  sessionId?: string
+): Promise<GeminiJsonEvent[]>
+```
+<!-- @source-ref-end -->
+
+Last synced: 2026-01-30 from commit abc1234
+```
+
+### Change Log Section
+
+```markdown
+## Specification Change Log
+
+<!-- @changelog-since: 2026-01-01 -->
+| Date | Commit | Section | Change |
+|------|--------|---------|--------|
+| 2026-01-28 | def5678 | Engine Selection | Added Ollama support |
+| 2026-01-15 | abc1234 | Session Resume | Fixed project path matching |
+<!-- @changelog-end -->
+```
+
+---
+
+## CLI Commands
+
+```bash
+# Validate all specs against current implementation
+mia-code rispecs validate
+
+# Check for drift since last validation
+mia-code rispecs check-drift
+
+# Suggest updates based on recent commits
+mia-code rispecs suggest-updates --since="1 week ago"
+
+# Apply suggested update interactively
+mia-code rispecs apply-update --interactive
+
+# Refresh source references and code blocks
+mia-code rispecs refresh-sources
+
+# Generate change log
+mia-code rispecs changelog --since="2026-01-01" --output=CHANGELOG.md
+```
+
+---
+
+## API Surface
+
+```typescript
+export class RispecsEngine {
+  // Lifecycle
+  static create(projectRoot: string): Promise<RispecsEngine>;
+  
+  // Analysis
+  analyzeCommits(since: string): Promise<SpecImpact[]>;
+  detectDrift(): Promise<DriftReport[]>;
+  validateCoverage(): Promise<CoverageReport>;
+  
+  // Updates
+  suggestUpdates(): Promise<SpecUpdate[]>;
+  applyUpdate(update: SpecUpdate): Promise<void>;
+  
+  // References
+  refreshReferences(): Promise<void>;
+  validateReferences(): Promise<ValidationResult>;
+  
+  // Generation
+  generateChangelog(options: ChangelogOptions): string;
+  
+  // Watching
+  watch(options: WatchOptions): Disposable;
+}
+
+interface CoverageReport {
+  totalSourceFiles: number;
+  referencedFiles: number;
+  unreferencedFiles: string[];
+  specFiles: string[];
+  coveragePercent: number;
+}
+
+interface ChangelogOptions {
+  since: string;
+  groupBy: 'commit' | 'spec' | 'date';
+  format: 'markdown' | 'json';
+}
+```
+
+---
+
+## Success Criteria
+
+✅ RispecsEngine detects spec-relevant commits automatically
+✅ Conventional commit scopes map to spec files
+✅ Source references update line numbers on code change
+✅ Drift detection identifies spec/code divergence
+✅ Change logs generated from git history
+✅ CLI commands integrate into mia-code workflow
+✅ Ceremonial logging for spec updates
+✅ Git hooks available for continuous validation
+
+---
+
+## References
+
+- mia-code existing rispecs: `/a/src/mia-code/rispecs/`
+- Conventional Commits: https://www.conventionalcommits.org/
+- Git commit analysis: `/a/src/memories/gist_research__coaia_memory_to_narrative_beats_251214.jsonl`

package/rispecs/mcp.rispecs.md

@@ -0,0 +1,197 @@
+# MCP Server Architecture Specification
+
+> RISE Framework Specification v1.0
+> Document: mia-code/rispecs/mcp.rispecs.md
+> Status: IMPLEMENTED
+
+## Creative Intent
+
+mia-code exposes its sub-CLI capabilities (miaco, miatel, miawa) as MCP (Model Context Protocol) servers, enabling external LLMs like Claude Code to invoke engineering, story, and ceremony tools directly. This transforms mia-code from a standalone agent into a composable toolset that any MCP-compatible host can orchestrate.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- Three sub-CLIs (miaco, miatel, miawa) exist as standalone Commander.js programs
+- Each has structured commands for its domain (charts, beats, ceremonies)
+- External agents cannot invoke these tools without shell spawning and output parsing
+- Claude Code's MCP integration expects JSON-RPC 2.0 over stdio
+
+**Desired Structural State:**
+- Each sub-CLI is accessible as a named MCP server (miaco, miatel, miawa)
+- Servers implement the MCP protocol: `initialize` → `tools/list` → `tools/call`
+- Tool schemas expose full inputSchema with properties, types, and required fields
+- External hosts connect via stdio transport and call tools by name
+- Tool handlers delegate to sub-CLI commands with `--json` output parsing
+
+## Architecture
+
+### Protocol Layer
+
+```
+Claude Code (or any MCP host)
+    │
+    ├── stdio ──→ miaco-server.js  (Engineering World)
+    ├── stdio ──→ miatel-server.js (Story World)
+    └── stdio ──→ miawa-server.js  (Ceremony World)
+```
+
+Each server is a standalone Node.js process that:
+1. Reads JSON-RPC 2.0 messages from stdin
+2. Handles `initialize`, `tools/list`, `tools/call` methods
+3. Writes JSON-RPC 2.0 responses to stdout
+4. Delegates tool execution to sub-CLI via `child_process.spawn`
+
+### Module Structure
+
+```
+src/mcp/
+├── utils.ts              # Shared: MCPTool/MCPToolResult types, runCLI,
+│                         #   parseJSONOutput, createToolResult, buildArgs,
+│                         #   bootstrapMCPServer (protocol handler)
+├── miaco-server.ts       # Tool definitions + handler + server startup
+├── miatel-server.ts      # Tool definitions + handler + server startup
+├── miawa-server.ts       # Tool definitions + handler + server startup
+├── config-generator.ts   # Generates MCP config JSON for host setup
+└── index.ts              # Registry: re-exports all servers + routing
+```
+
+Each `*-server.ts` file serves dual purpose:
+- **Library mode:** Exports tools array, handler function, and config for use by `index.ts` and `config-generator.ts`
+- **Server mode:** When run directly (`node miaco-server.js`), starts the MCP protocol handler via `bootstrapMCPServer()`
+
+### Server Startup Detection
+
+```typescript
+const isMain = process.argv[1] && (
+  process.argv[1].endsWith("miaco-server.js") ||
+  process.argv[1].endsWith("miaco-server.ts")
+);
+if (isMain) {
+  bootstrapMCPServer(config, handler);
+}
+```
+
+### Protocol Bootstrap
+
+`bootstrapMCPServer()` in `utils.ts` uses `@modelcontextprotocol/sdk`:
+- `Server` class (low-level) for direct JSON schema passthrough
+- `StdioServerTransport` for stdio communication
+- `ListToolsRequestSchema` handler returns tool definitions with full inputSchema
+- `CallToolRequestSchema` handler routes to the appropriate tool handler
+
+### Tool Execution Flow
+
+```
+MCP Host sends: tools/call { name: "miaco_chart_create", arguments: {...} }
+    ↓
+CallToolRequestSchema handler
+    ↓
+handleMiacoTool("miaco_chart_create", args)
+    ↓
+buildArgs(["chart", "create"], args, { outcome: "--outcome", ... })
+    ↓
+runCLI(CLI_PATH, [...cliArgs, "--json"])
+    → spawn("node", ["/path/to/miaco/dist/index.js", "chart", "create", ...])
+    ↓
+parseJSONOutput(stdout)
+    ↓
+createToolResult(parsed) → { content: [{ type: "text", text: "..." }] }
+```
+
+## Configuration
+
+### Host Configuration (`.mcp.mia-code.json`)
+
+```json
+{
+  "mcpServers": {
+    "miatel": {
+      "command": "node",
+      "args": ["/a/src/mia-code/dist/mcp/miatel-server.js"],
+      "env": {}
+    },
+    "miawa": {
+      "command": "node",
+      "args": ["/a/src/mia-code/dist/mcp/miawa-server.js"],
+      "env": {}
+    },
+    "miaco": {
+      "command": "node",
+      "args": ["/a/src/mia-code/dist/mcp/miaco-server.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+Place this file in the project root or parent directory (e.g., `/a/src/.mcp.mia-code.json`).
+
+### Programmatic Config Generation
+
+```bash
+mia-code mcp-config              # JSON config for Claude Code
+mia-code mcp-config --tools      # Tool manifest (all tools with schemas)
+mia-code mcp-config --info       # Server metadata + tools
+```
+
+## Tool Catalog
+
+### miaco (Engineering World) — 8 tools
+
+| Tool | Purpose | Required Args |
+|------|---------|---------------|
+| `miaco_chart_create` | Create structural tension chart | outcome, reality |
+| `miaco_chart_list` | List active charts | — |
+| `miaco_chart_add_step` | Add action step to chart | chart, title, reality |
+| `miaco_chart_complete` | Mark step complete | step |
+| `miaco_chart_review` | Review with Creator Moment | chart |
+| `miaco_decompose` | PDE prompt decomposition | prompt |
+| `miaco_decompose_list` | List stored decompositions | — |
+| `miaco_decompose_get` | Get specific decomposition | id |
+
+### miatel (Story World) — 4 tools
+
+| Tool | Purpose | Required Args |
+|------|---------|---------------|
+| `miatel_beat_create` | Create story beat | text |
+| `miatel_beat_list` | List beats in session | — |
+| `miatel_beat_analyze` | Analyze beat with lens | beatId |
+| `miatel_beat_enrich` | Apply emotional enrichment | beatId |
+
+### miawa (Ceremony World) — 6 tools
+
+| Tool | Purpose | Required Args |
+|------|---------|---------------|
+| `miawa_ceremony_init` | Initiate ceremony | title, type |
+| `miawa_ceremony_list` | List ceremonies | — |
+| `miawa_ceremony_advance` | Advance to next movement | ceremony |
+| `miawa_ceremony_close` | Close with wisdom archiving | — |
+| `miawa_ceremony_wisdom` | Retrieve archived wisdom | — |
+| `miawa_ceremony_stage` | Check Four Movements stage | — |
+
+## Dependencies
+
+- `@modelcontextprotocol/sdk` — MCP protocol implementation (Server, StdioServerTransport)
+- Sub-CLI builds must be present at `miaco/dist/`, `miatel/dist/`, `miawa/dist/`
+- Node.js `child_process` for CLI delegation
+
+## Known Constraints
+
+- Tool handlers spawn sub-CLI processes — each tool call incurs process creation overhead
+- Sub-CLI `--json` output support is required for all commands exposed as tools
+- Session ID can be passed via tool args or `MIA_SESSION_ID` environment variable
+- Error handling: CLI failures return `{ isError: true, content: [{ type: "text", text: error }] }`
+
+## Creative Advancement Scenario
+
+**Desired Outcome:** Claude Code agent uses mia-code tools to create a structural tension chart during a coding session.
+
+**Natural Progression:**
+1. Developer launches Claude Code in project with `.mcp.mia-code.json`
+2. Claude Code connects to miaco MCP server via stdio
+3. Agent calls `miaco_chart_create` with outcome and reality
+4. Server delegates to `miaco chart create --outcome "..." --reality "..." --json`
+5. JSON response flows back through MCP protocol
+6. Agent uses chart ID to add steps, track progress, review
+
+**Achieved Outcome:** External agent seamlessly uses mia-code's engineering tools without shell scripting or output parsing.