ruvnet-kb-first 5.0.0

package/phases/05-integration.md

@@ -0,0 +1,114 @@
+# Phase 5: KB Integration Layer
+
+## Purpose
+
+Generate a TypeScript SDK that the application uses to access the knowledge base. This becomes the **only** way the app interacts with the KB.
+
+---
+
+## Output Structure
+
+```
+src/kb/
+├── client.ts       # Core query functions
+├── types.ts        # TypeScript interfaces  
+├── tree.ts         # Tree navigation functions
+├── validator.ts    # Startup verification
+└── index.ts        # Single export point
+```
+
+---
+
+## Template: types.ts
+
+See `templates/kb-client.ts` for the full implementation.
+
+Key interfaces:
+- `KBNode` — A knowledge base node
+- `KBSource` — Attribution for a response
+- `KBResponse<T>` — Wrapper with sources and confidence
+- `KBHealth` — Connection health status
+
+---
+
+## Template: client.ts
+
+Core functions:
+- `search(query, namespace)` — Semantic search
+- `getByPath(namespace, path)` — Get specific node
+- `getChildren(namespace, path)` — Get child nodes
+- `logGap(query, namespace)` — Log unanswered query
+
+Every function returns `KBResponse<T>` with:
+- `data` — The actual result
+- `kbSources` — Expert attribution
+- `confidence` — 0.0-1.0 score
+- `gap` — Whether this was unanswerable
+
+---
+
+## Template: validator.ts
+
+```typescript
+export async function verifyConnection(): Promise<KBHealth> {
+  try {
+    const result = await pool.query(`
+      SELECT 
+        COUNT(*) as node_count,
+        (SELECT COUNT(*) FROM kb_gaps) as gap_count
+      FROM kb_nodes
+    `);
+    
+    return {
+      healthy: true,
+      nodeCount: parseInt(result.rows[0].node_count),
+      gapCount: parseInt(result.rows[0].gap_count),
+      features: await detectFeatures()
+    };
+  } catch (error) {
+    return {
+      healthy: false,
+      nodeCount: 0,
+      gapCount: 0,
+      features: {},
+      error: error.message
+    };
+  }
+}
+```
+
+---
+
+## Template: index.ts
+
+```typescript
+export * from './types';
+export * from './client';
+export * from './tree';
+export { verifyConnection } from './validator';
+
+// Re-export as named 'kb'
+import * as client from './client';
+import * as tree from './tree';
+import { verifyConnection } from './validator';
+
+export const kb = {
+  ...client,
+  ...tree,
+  verifyConnection
+};
+```
+
+---
+
+## Quality Gate
+
+- [ ] All files compile without errors
+- [ ] Exports work correctly
+- [ ] `verifyConnection()` returns health status
+- [ ] `search()` returns results with sources
+- [ ] `logGap()` logs unanswered queries
+
+---
+
+**Proceed to Phase 6: Application Scaffold**

package/phases/06-scaffold.md

@@ -0,0 +1,130 @@
+# Phase 6: Application Scaffold
+
+## Purpose
+
+Create the project structure with KB enforcement built in from the start.
+
+---
+
+## Output Structure
+
+```
+[PROJECT]/
+├── src/
+│   ├── kb/              # FROM PHASE 5 (treat as read-only)
+│   │   ├── client.ts
+│   │   ├── types.ts
+│   │   ├── tree.ts
+│   │   ├── validator.ts
+│   │   └── index.ts
+│   │
+│   ├── intelligence/    # GNN/Attention/SONA (based on pattern)
+│   │   ├── gnn.ts       # If Decision Web
+│   │   ├── attention.ts # If Routing
+│   │   └── sona.ts      # If Learning
+│   │
+│   ├── domain/          # Domain logic (MUST use kb/)
+│   │   └── [domain-specific files]
+│   │
+│   ├── api/             # Routes
+│   │   └── routes/
+│   │
+│   ├── components/      # UI components
+│   │
+│   ├── pages/           # Page compositions
+│   │
+│   └── index.ts         # Entry point (KB verification FIRST)
+│
+├── visualization/       # From Phase 4
+│
+├── scripts/             # Verification scripts
+│   ├── verify-domain.sh
+│   ├── verify-api.sh
+│   └── verify-entry.sh
+│
+├── KB_ENFORCEMENT.md    # Rules document
+│
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+## KB_ENFORCEMENT.md
+
+Create this file in the project root and keep it in context throughout development:
+
+```markdown
+# KB ENFORCEMENT RULES
+
+This document defines the rules for KB-First development.
+ALL code must comply with these rules.
+
+## Rule 1: No Hardcoded Domain Logic
+Every domain value comes from the KB.
+
+## Rule 2: Every Domain Function Queries KB  
+Every file in src/domain/ imports from ../kb
+
+## Rule 3: All Responses Include kbSources
+Traceability is mandatory.
+
+## Rule 4: Startup Verification Required
+App exits if KB unavailable.
+
+## Rule 5: No Fallback Logic
+KB is the source of truth.
+
+See phases/07-build.md for full details and examples.
+```
+
+---
+
+## Entry Point Template
+
+```typescript
+// src/index.ts
+import { kb } from './kb';
+import { initializeApp } from './app';
+
+async function main() {
+  console.log('Starting application...');
+  
+  // FIRST: Verify KB connection
+  console.log('Verifying knowledge base...');
+  const health = await kb.verifyConnection();
+  
+  if (!health.healthy) {
+    console.error('KB unavailable:', health.error);
+    console.error('Cannot start application without knowledge base.');
+    process.exit(1);
+  }
+  
+  console.log(`KB ready: ${health.nodeCount} nodes, ${health.gapCount} logged gaps`);
+  
+  // THEN: Initialize application
+  await initializeApp();
+  
+  console.log('Application started successfully');
+}
+
+main().catch((error) => {
+  console.error('Startup failed:', error);
+  process.exit(1);
+});
+```
+
+---
+
+## Quality Gate
+
+- [ ] Directory structure created
+- [ ] KB_ENFORCEMENT.md in project root
+- [ ] Entry point verifies KB first
+- [ ] Entry point exits on KB failure
+- [ ] Domain directory empty (ready for Phase 7)
+
+---
+
+**Proceed to Phase 7: Application Build**