mindforge-cc 9.0.0 → 10.0.0

package/docs/sdk-reference.md

@@ -1,27 +1,377 @@
 # MindForge SDK Reference
 
 ## Overview
-The `@mindforge/sdk` package provides a programmatic API for integrating MindForge
-into tools, dashboards, and CI pipelines.
-
-## API
-
-### `MindForgeClient`
-- `isInitialised(): boolean`
-- `readState(): object | null`
-- `readHandoff(): object | null`
-- `health(): Promise<HealthReport>`
-- `readAuditLog(filter?): unknown[]`
-- `readSessionMetrics(limit?): unknown[]`
-- `validateConfig(): { valid, errors, warnings }`
-
-### `MindForgeEventStream`
-- `start(port = 7337)` — starts localhost-only SSE server
-- `watchAuditLog(projectRoot)` — streams new AUDIT.jsonl entries
-- `broadcast(eventType, data)` — manual broadcast
-- `stop()` — shutdown server and watchers
-
-## Security considerations
-- The SDK reads local files that may contain sensitive data.
-- The event stream is bound to localhost only and rejects remote connections.
-- Do not expose SDK endpoints to public networks.
+
+The `@mindforge/sdk` package provides a programmatic TypeScript API for integrating
+MindForge into tools, dashboards, and CI pipelines. Import from `@mindforge/sdk`.
+
+```typescript
+import {
+  MindForgeClient,
+  MindForgeEventStream,
+  MindForgeMemory,
+  commands,
+} from '@mindforge/sdk';
+```
+
+Current SDK version: `10.0.0`
+
+---
+
+## `MindForgeClient`
+
+Main client for reading project state, health checks, audit logs, and configuration.
+
+### Constructor
+
+```typescript
+new MindForgeClient(config?: MindForgeConfig)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `config.projectRoot` | `string` | `process.cwd()` | Path to the project root |
+| `config.apiKey` | `string` | `ANTHROPIC_API_KEY` env var | Claude API key |
+| `config.ciMode` | `boolean` | `CI === 'true'` | Disables interactive features |
+| `config.outputFormat` | `'json' \| 'text' \| 'github-annotations'` | `'json'` | Output format for events |
+| `config.taskTimeoutMs` | `number` | `600000` | Timeout per task in milliseconds |
+
+### Methods
+
+#### `isInitialised(): boolean`
+
+Returns `true` if the project has a `.planning/PROJECT.md` file, indicating MindForge
+has been initialized in this repository.
+
+#### `readState(): Record<string, unknown> | null`
+
+Reads `.planning/STATE.md` and returns its raw content. Returns `null` if the file
+does not exist.
+
+#### `readHandoff(): Record<string, unknown> | null`
+
+Reads and parses `.planning/HANDOFF.json`. Returns the parsed object or `null` if
+the file does not exist or cannot be parsed.
+
+#### `health(): Promise<HealthReport>`
+
+Runs a health check across required files (`STATE.md`, `HANDOFF.json`, `AUDIT.jsonl`,
+`CONVENTIONS.md`), validates HANDOFF schema, and reports audit log size. Returns a
+`HealthReport` with `overallStatus` of `'healthy'`, `'warning'`, or `'error'`.
+
+#### `readAuditLog(filter?): AuditLogEntry[]`
+
+Reads `.planning/AUDIT.jsonl` and returns parsed entries. Supports optional filtering:
+
+| Filter | Type | Description |
+|--------|------|-------------|
+| `event` | `string` | Filter by event type |
+| `phase` | `number` | Filter by phase number |
+| `since` | `Date` | Only entries after this date |
+
+#### `readSessionMetrics(limit?: number): unknown[]`
+
+Reads the last `limit` entries (default: 10) from
+`.mindforge/metrics/session-quality.jsonl`.
+
+#### `validateConfig(): { valid: boolean; errors: string[]; warnings: string[] }`
+
+Validates the project's `MINDFORGE.md` configuration file. Returns validation results
+with any errors or warnings found.
+
+#### `readAutoState(): Record<string, unknown> | null`
+
+Reads `.planning/auto-state.json` — the persistent state file for the autonomous
+wave execution engine (v9 Pillar XXIV). Returns `null` if the file does not exist.
+
+#### `isDatabaseInitialized(): boolean`
+
+Returns `true` if the unified SQLite knowledge database (`celestial.db`) exists at
+`.mindforge/celestial.db` (v9 Pillar XXVI).
+
+#### `getDbPath(): string`
+
+Returns the absolute path to the project's `celestial.db` SQLite database file.
+
+---
+
+## `MindForgeMemory`
+
+Client for the Knowledge Graph (RAG 2.0). Manages persistent knowledge entries,
+typed graph edges, semantic search, and auto-shadowing.
+
+### Constructor
+
+```typescript
+new MindForgeMemory(projectRoot?: string)
+```
+
+### Knowledge Store Methods
+
+#### `remember(entry: Partial<KnowledgeEntry>): Promise<string>`
+
+Adds a new knowledge entry to the store. Returns the generated entry ID.
+
+#### `query(params?: QueryParams): Promise<KnowledgeEntry[]>`
+
+Queries the knowledge base with optional filters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `tags` | `string[]` | Filter by tags |
+| `topic` | `string` | Filter by topic |
+| `type` | `KnowledgeType` | Filter by entry type |
+| `minConfidence` | `number` | Minimum confidence threshold |
+| `limit` | `number` | Max results |
+| `includeGlobal` | `boolean` | Include global knowledge base |
+| `includeDeprecated` | `boolean` | Include deprecated entries |
+| `project` | `string` | Filter by project name |
+
+#### `reinforce(id: string): Promise<void>`
+
+Increases the confidence score of an existing entry.
+
+#### `deprecate(id: string, reason: string, supersededBy?: string): Promise<void>`
+
+Marks an entry as deprecated with a reason and optional replacement ID.
+
+#### `getStats(): Promise<MemoryStats>`
+
+Returns aggregate statistics: total entries, active/deprecated counts, breakdown by
+type, and average confidence.
+
+#### `loadContext(opts): Promise<SessionContext>`
+
+Loads relevant knowledge for a session. Accepts `techStack`, `phase`, and `topic` as
+filters. Returns categorized entries (preferences, decisions, bug patterns, code
+patterns, domain knowledge) with a pre-formatted string.
+
+### Knowledge Graph Methods
+
+#### `addEdge(edge): Promise<string>`
+
+Adds a typed, weighted edge between two knowledge nodes. Returns the edge ID.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sourceId` | `string` | Yes | Source node ID |
+| `targetId` | `string` | Yes | Target node ID |
+| `type` | `EdgeType` | Yes | One of: `RELATED_TO`, `CAUSED_BY`, `SUPERSEDES`, `DEPENDS_ON`, `INFORMS`, `CONTRADICTS` |
+| `weight` | `number` | No | Edge weight (0-1) |
+| `reason` | `string` | No | Why this relationship exists |
+
+#### `getEdges(nodeId: string, opts?): Promise<GraphEdge[]>`
+
+Gets all edges for a node. Options: `direction` (`'outgoing'`, `'incoming'`, `'both'`)
+and `edgeTypes` filter array.
+
+#### `traverse(startId: string, maxDepth?: number, opts?): Promise<TraversalResult[]>`
+
+BFS traversal from a starting node. Options: `edgeTypes` and `minWeight` filters.
+
+#### `findRelated(queryText: string, opts?): Promise<Array<{ id, score, source }>>`
+
+Hybrid embedding + graph search. Returns ranked results by relevance score. Options:
+`maxHops` and `topK`.
+
+#### `autoShadow(opts): Promise<ShadowContext>`
+
+Generates auto-shadow context for a task description. Retrieves the most relevant
+knowledge entries based on semantic similarity and graph proximity.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `taskDescription` | `string` | Yes | What you are working on |
+| `excludeIds` | `string[]` | No | Entry IDs to skip |
+| `techStack` | `string[]` | No | Relevant technologies |
+
+#### `getGraphStats(): Promise<GraphStats>`
+
+Returns graph-level statistics: total nodes, total edges, edges by type, orphan count,
+average weight, and connected ratio.
+
+#### `decayEdges(): Promise<{ decayed: number; pruned: number }>`
+
+Applies time-based weight decay to stale edges and prunes edges below threshold.
+
+#### `detectCycles(): Promise<string[][]>`
+
+Detects cycles in directed edge types. Returns arrays of node IDs forming each cycle.
+
+#### `verifyIntegrity(): Promise<{ valid: number; corrupted: string[] }>`
+
+Verifies SHA-256 checksums of all edges. Returns count of valid edges and IDs of any
+corrupted edges.
+
+---
+
+## `MindForgeEventStream`
+
+Localhost-only SSE (Server-Sent Events) server for real-time execution progress.
+
+### Methods
+
+#### `start(port?: number): Promise<void>`
+
+Starts the SSE server bound to `127.0.0.1` on the given port (default: `7337`).
+Clients connect at `http://localhost:<port>/events`. Rejects non-localhost connections
+with HTTP 403.
+
+#### `watchAuditLog(projectRoot: string): void`
+
+Watches `.planning/AUDIT.jsonl` for new entries and broadcasts each as an
+`audit_entry` SSE event to all connected clients.
+
+#### `broadcast(eventType: string, data: unknown): void`
+
+Manually broadcasts a named event to all connected SSE clients.
+
+#### `stop(): void`
+
+Shuts down the HTTP server, closes the audit file watcher, and disconnects all clients.
+
+---
+
+## `commands`
+
+Builder utilities that produce command strings for programmatic use with Claude Code
+or Antigravity APIs.
+
+### Methods
+
+#### `commands.health(opts?: CommandOptions): string`
+
+Returns `/mindforge:health [flags]`.
+
+#### `commands.planPhase(phase: number, opts?: CommandOptions): string`
+
+Returns `/mindforge:plan-phase <phase> [flags]`.
+
+#### `commands.executePhase(phase: number, opts?: CommandOptions): string`
+
+Returns `/mindforge:execute-phase <phase> [flags]`.
+
+#### `commands.securityScan(path?: string, opts?: CommandOptions): string`
+
+Returns `/mindforge:security-scan [path] [flags]`.
+
+#### `commands.audit(filter?): string`
+
+Returns `/mindforge:audit [--phase N] [--event E] [--since S]`.
+
+#### `commands.prReview(opts?: CommandOptions): string`
+
+Returns `/mindforge:pr-review [flags]`.
+
+---
+
+## Exported Types
+
+### `MindForgeConfig`
+
+Configuration object for `MindForgeClient`. All fields are optional.
+
+### `HealthReport`
+
+```typescript
+{
+  overallStatus: 'healthy' | 'warning' | 'error';
+  errors: HealthIssue[];
+  warnings: HealthIssue[];
+  informational: HealthIssue[];
+  timestamp: string;
+}
+```
+
+### `HealthIssue`
+
+```typescript
+{ category: string; message: string; autoRepairable: boolean; fixCommand?: string }
+```
+
+### `AuditLogEntry`
+
+```typescript
+{ timestamp: string; event: string; phase?: number; [key: string]: unknown }
+```
+
+### `PhaseResult`
+
+Result of a complete phase execution, including task counts, commits, security findings,
+gate results, and duration.
+
+### `TaskResult`
+
+Result of a single task execution with status, optional commit SHA, verify output,
+and duration.
+
+### `SecurityFinding`
+
+```typescript
+{
+  severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
+  owaspCategory: string;
+  file: string; line: number;
+  description: string; remediation: string; remediated: boolean;
+}
+```
+
+### `GateResult`
+
+```typescript
+{ gate: string; status: 'passed' | 'failed' | 'warning' | 'skipped'; detail?: string }
+```
+
+### `MindForgeEvent`
+
+Discriminated union of all real-time events: `task_started`, `task_completed`,
+`task_failed`, `wave_started`, `wave_completed`, `phase_completed`,
+`security_finding`, `gate_result`, `log`.
+
+### `WaveExecutionResult`
+
+Result from a single wave execution cycle (v9 Pillar XXIV), including task counts,
+failures list, duration, and status.
+
+### `MigrationResult`
+
+Result from a schema migration run (v9 Pillar XXVII), including migration status,
+version range, migrations applied, and backup directory.
+
+### `KnowledgeEntry`
+
+Full knowledge store entry with metadata (type, topic, content, confidence, tags,
+links, deprecation state) and type-specific fields.
+
+### `KnowledgeType`
+
+```typescript
+'architectural_decision' | 'code_pattern' | 'bug_pattern' | 'team_preference' | 'domain_knowledge'
+```
+
+### `EdgeType`
+
+```typescript
+'RELATED_TO' | 'CAUSED_BY' | 'SUPERSEDES' | 'DEPENDS_ON' | 'INFORMS' | 'CONTRADICTS'
+```
+
+### `GraphEdge`
+
+Full edge record with source/target IDs, type, weight, reason, metadata, traversal
+count, deprecation state, and SHA-256 checksum.
+
+### `CommandOptions`
+
+```typescript
+{ flags?: string[]; args?: string[] }
+```
+
+---
+
+## Security Considerations
+
+- The SDK reads local files that may contain sensitive data (audit logs, state).
+- The event stream binds to `127.0.0.1` only and rejects remote connections with 403.
+- CORS is restricted to localhost origins (exact match, no wildcards).
+- Do not expose SDK endpoints or the SSE server to public networks.
+- API keys passed via `MindForgeConfig` are held in memory only — never written to disk.

package/docs/troubleshooting.md

@@ -1,4 +1,4 @@
-# MindForge Troubleshooting (v5.1.0)
+# MindForge Troubleshooting (v10.0.0)
 
 This page lists common issues and fast fixes. If you get stuck, start with
 `/mindforge:health`.
@@ -54,14 +54,14 @@ npx mindforge-cc@latest --claude --local --force
 ```
 Then run:
 ```
-/mindforge:migrate --from v5.0.0 --to v5.1.0
+/mindforge:migrate --from v9.0.0 --to v10.0.0
 ```
 
 ### Schema mismatch warning on startup
 **Fix:**
 ```
 /mindforge:migrate --dry-run
-/mindforge:migrate --from vX.Y.Z --to v5.1.0
+/mindforge:migrate --from vX.Y.Z --to v10.0.0
 ```
 
 ### AUDIT.jsonl parse errors
@@ -113,7 +113,7 @@ rerun migration. See `.mindforge/audit/AUDIT-SCHEMA.md` for expected format.
 
 ---
 
-## 8. Neural Protocol Mesh Issues (v5.1.0)
+## 8. Neural Protocol Mesh Issues
 
 ### Protocol Step 0 fails to activate
 **Symptom:** Commands proceed without activating `_extended` skills.

package/examples/sdk-integration/README.md

@@ -0,0 +1,24 @@
+# SDK Integration Example
+
+Demonstrates basic usage of the `@mindforge/sdk` package.
+
+## Prerequisites
+
+- Node.js >= 18
+- A MindForge-initialized project (with `MINDFORGE.md` at the root)
+
+## Running
+
+```bash
+# From the repository root, build the SDK first
+cd sdk && npm run build && cd ..
+
+# Run the example (uses the repo root as the project)
+node examples/sdk-integration/index.js
+```
+
+## What it does
+
+1. Reads project state from `.planning/STATE.md`
+2. Validates `MINDFORGE.md` configuration against required fields
+3. Reads the audit log from `.planning/AUDIT.jsonl`

package/examples/sdk-integration/index.js

@@ -0,0 +1,24 @@
+const { MindForgeClient, MindForgeEventStream } = require('@mindforge/sdk');
+
+async function main() {
+  const client = new MindForgeClient();
+
+  // Check project health
+  const state = client.readState();
+  console.log('Project state:', state ? 'initialized' : 'not initialized');
+
+  // Validate configuration
+  const validation = client.validateConfig();
+  if (!validation.valid) {
+    console.error('Config issues:', validation.errors);
+    return;
+  }
+
+  // Read audit log
+  const entries = client.readAuditLog();
+  console.log(`Audit entries: ${entries.length}`);
+
+  console.log('MindForge SDK integration working!');
+}
+
+main().catch(console.error);

package/examples/starter-project/MINDFORGE.md

@@ -1,15 +1,15 @@
 NAME=ExampleProject
 VERSION=1.0.0
-DESCRIPTION=Starter example for MindForge v1.0.0
-MINDFORGE_VERSION_REQUIRED=1.0.0
+DESCRIPTION=Starter example for MindForge v10.0.0
+MINDFORGE_VERSION_REQUIRED=10.0.0
 
 # Model preferences
-PLANNER_MODEL=claude-sonnet-4-5
-EXECUTOR_MODEL=claude-sonnet-4-5
-REVIEWER_MODEL=claude-sonnet-4-5
-VERIFIER_MODEL=claude-sonnet-4-5
-SECURITY_MODEL=claude-opus-4-5
-DEBUG_MODEL=claude-opus-4-5
+PLANNER_MODEL=claude-sonnet-4-6
+EXECUTOR_MODEL=claude-sonnet-4-6
+REVIEWER_MODEL=claude-sonnet-4-6
+VERIFIER_MODEL=claude-sonnet-4-6
+SECURITY_MODEL=claude-opus-4-7
+DEBUG_MODEL=claude-opus-4-7
 
 # Execution behavior
 TIER1_AUTO_APPROVE=true

package/package.json

@@ -1,28 +1,39 @@
 {
   "name": "mindforge-cc",
-  "version": "9.0.0",
-  "description": "MindForge — Sovereign Agentic Intelligence Framework. Bedrock Meridian: Grounded Execution (Pillars XXIV-XXVIII)",
+  "version": "10.0.0",
+  "description": "MindForge — Sovereign Agentic Intelligence Framework. Bedrock Fortified: Production-Grade Architecture (v10)",
   "bin": {
-    "mindforge-cc": "bin/install.js"
+    "mindforge-cc": "bin/install.js",
+    "mindforge": "bin/mindforge-cli.js"
   },
   "files": [
-    ".agent/",
-    ".claude/",
-    ".mindforge/",
-    ".planning/",
+    ".agent/CLAUDE.md",
+    ".agent/hooks/",
+    ".mindforge/MINDFORGE-SCHEMA.json",
+    ".mindforge/MINDFORGE-V2-SCHEMA.json",
+    ".mindforge/config.json",
+    ".mindforge/personas/",
+    ".mindforge/skills/",
+    ".mindforge/engine/",
     "bin/",
-    "docs/",
+    "docs/getting-started.md",
+    "docs/user-guide.md",
+    "docs/sdk-reference.md",
+    "docs/commands-reference.md",
+    "docs/troubleshooting.md",
+    "docs/faq.md",
     "examples/",
     "CHANGELOG.md",
     "LICENSE",
     "MINDFORGE.md",
     "README.md",
     "RELEASENOTES.md",
-    "SECURITY.md",
-    "package.json"
+    "SECURITY.md"
   ],
   "scripts": {
-    "test": "node tests/install.test.js",
+    "test": "node tests/run-all.js",
+    "test:single": "node",
+    "coverage": "npx c8 node tests/run-all.js",
     "lint": "eslint .",
     "commit": "cz",
     "prepare": "husky"
@@ -48,7 +59,8 @@
   "devDependencies": {
     "@eslint/js": "^9.0.0",
     "@types/node": "^20.0.0",
-    "commitizen": "4.3.1",
+    "c8": "^10.0.0",
+    "commitizen": "^4.2.4",
     "cz-conventional-changelog": "3.3.0",
     "eslint": "^9.0.0",
     "globals": "^15.0.0",
@@ -59,8 +71,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "better-sqlite3": "^12.8.0",
     "express": "^4.19.2",
-    "kysely": "^0.28.16"
+    "sql.js": "^1.14.1"
   }
 }