agentic-orchestrator 0.1.28 → 0.2.1

package/docs/core/PATTERNS.md

@@ -0,0 +1,201 @@
+# Implementation Patterns: agentic-orchestrator
+
+---
+
+## Pattern 1: Returning Errors — Use `fail()` + `ERROR_CODES`
+
+**Rule**: Never throw raw errors from service methods or tool handlers. Always return a structured `ToolResponse` using `fail()` with a code from `ERROR_CODES`.
+
+### ❌ Anti-Pattern
+
+```typescript
+// WRONG: throws instead of returns; uses raw string instead of ERROR_CODES
+throw new Error('lock not held');
+```
+
+### ✅ Canonical Example
+
+**Source File**: `apps/control-plane/src/application/services/lock-service.ts`
+
+```typescript
+import { fail, ok } from '../../core/response.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+
+function releaseLock(featureId: string, sessionId: string): ToolResponse {
+  if (!isOwner(featureId, sessionId)) {
+    return fail(
+      ERROR_CODES.LOCK_NOT_HELD,
+      `Session ${sessionId} does not hold lock for ${featureId}`,
+      { retryable: false, requires_human: false, featureId, sessionId },
+    );
+  }
+  // ...release...
+  return ok({ released: true });
+}
+```
+
+### 🔗 References
+
+- **Domain Logic**: `DOMAIN-LOGIC.md` rules 12–14
+- **Error codes**: `apps/control-plane/src/core/error-codes.ts`
+- **Response helpers**: `apps/control-plane/src/core/response.ts`
+
+---
+
+## Pattern 2: Port-Based Dependency Injection
+
+**Rule**: Services expose an interface (port). The kernel constructs them as concrete implementations. Domain/application layers only depend on the interface, never the concrete class.
+
+### ❌ Anti-Pattern
+
+```typescript
+// WRONG: domain class directly instantiates infrastructure
+import { GitHubPRClient } from '../infra/github-client.js';
+class MergeService {
+  client = new GitHubPRClient(); // hard coupling
+}
+```
+
+### ✅ Canonical Example
+
+**Source File**: `apps/control-plane/src/application/services/merge-service.ts`
+
+```typescript
+// Define the port (interface)
+export interface MergeServicePort {
+  getRepoRoot(): string;
+  getPolicySnapshot(): AnyRecord;
+  // ...additional port methods
+}
+
+// Implement the service, depending on the port
+export class MergeService {
+  private readonly port: MergeServicePort;
+  constructor(port: MergeServicePort) {
+    this.port = port;
+  }
+  // ...
+}
+
+// Kernel wires it at construction time, passing the port implementation
+const mergeService = new MergeService(port);
+```
+
+### 🔗 References
+
+- **Architecture**: `ARCHITECTURE.md` — Component Map (Port-based DI row)
+- **Domain Logic**: `DOMAIN-LOGIC.md` rule 15
+
+---
+
+## Pattern 3: Atomic State Reads and Writes
+
+**Rule**: Always wrap file-based state mutations with `withFileLock()`. Never read-modify-write `state.md`, `plan.json`, or `index.json` without holding the lock.
+
+### ❌ Anti-Pattern
+
+```typescript
+// WRONG: reads then writes without a lock — race condition in parallel runs
+const state = await readJson(statePath);
+state.status = 'building';
+await atomicWriteJson(statePath, state);
+```
+
+### ✅ Canonical Example
+
+**Source File**: `apps/control-plane/src/application/services/feature-state-service.ts`
+
+```typescript
+import { withFileLock, readJson, atomicWriteJson } from '../../core/fs.js';
+
+async function transitionStatus(statePath: string, newStatus: string): Promise<ToolResponse> {
+  return withFileLock(statePath, async () => {
+    const state = await readJson(statePath);
+    // validate transition before mutating
+    const allowed = LEGAL_TRANSITIONS[state.status];
+    if (!allowed?.includes(newStatus)) {
+      return fail(
+        ERROR_CODES.INVALID_STATUS_TRANSITION,
+        `Cannot go from ${state.status} to ${newStatus}`,
+      );
+    }
+    state.status = newStatus;
+    await atomicWriteJson(statePath, state);
+    return ok({ status: newStatus });
+  });
+}
+```
+
+### 🔗 References
+
+- **Domain Logic**: `DOMAIN-LOGIC.md` rules 4–6
+- **Utilities**: `apps/control-plane/src/core/fs.ts`
+
+---
+
+## Pattern 4: Adding a New CLI Command
+
+**Rule**: Adding a new command requires updating **all five** of the following files in the same commit. Missing any one will cause lint or runtime failures.
+
+### ✅ Checklist
+
+1. **`apps/control-plane/src/cli/types.ts`** — add value to `CliCommand` enum
+2. **`apps/control-plane/src/cli/cli-argument-parser.ts`** — parse the new token
+3. **`apps/control-plane/src/interfaces/cli/bootstrap.ts`** — dispatch the new command
+4. **`apps/control-plane/src/cli/help-command-handler.ts`** — add to `COMMAND_HELP` (summary + flags list)
+5. **`CLAUDE.md` and `AGENTS.md`** — update command list in CLI bullet point
+
+### 🔗 References
+
+- **CLAUDE.md**: `CLAUDE.md` § Adding a New CLI Command or Flag
+- **AGENTS.md**: `AGENTS.md` § Adding a New CLI Command or Flag
+
+---
+
+## Pattern 5: MCP Tool Idempotency
+
+**Rule**: All mutating MCP tool calls must include `operation_id`. The operation ledger deduplicates retried calls automatically — callers must provide the ID, not check for duplicates themselves.
+
+### ✅ Canonical Example
+
+**Source File**: `apps/control-plane/src/mcp/operation-ledger.ts`
+
+```typescript
+// Caller provides a stable operation_id (e.g., derived from feature + patch sequence)
+const result = await toolRuntime.executeTool({
+  tool: 'repo.apply_patch',
+  input: { featureId, patch },
+  operation_id: `${featureId}:patch:${patchSeq}`,
+  role: 'builder',
+});
+```
+
+### 🔗 References
+
+- **Domain Logic**: `DOMAIN-LOGIC.md` rule 9
+- **Tool catalog**: `config/agentic/orchestrator/tools/catalog.json`
+
+---
+
+## Pattern 6: Structured TypeScript Imports
+
+**Rule**: Use `import type` for any import used only as a type. ESLint `consistent-type-imports` is enforced — violations are errors.
+
+### ❌ Anti-Pattern
+
+```typescript
+import { ToolResponse } from '../../core/response.js'; // used only as a type
+```
+
+### ✅ Canonical Example
+
+```typescript
+import type { ToolResponse } from '../../core/response.js';
+import { ok, fail } from '../../core/response.js'; // runtime values
+```
+
+### 🔗 References
+
+- **CLAUDE.md** § Lint Rules to Know
+
+<!-- @cortex-tms-version 4.0.2 -->

package/docs/core/TROUBLESHOOTING.md

@@ -0,0 +1,347 @@
+# Troubleshooting: Known Issues & Solutions
+
+<!-- This file documents framework gotchas, common errors, and workarounds. -->
+<!-- Help AI agents avoid known pitfalls by documenting them here. -->
+
+---
+
+## 🎯 Purpose
+
+This file exists to prevent AI agents from:
+
+- Implementing patterns that won't work in your framework
+- Making assumptions that contradict framework behavior
+- Wasting time debugging known issues
+
+**When to add an entry**: Anytime you encounter a non-obvious error that took more than 30 minutes to debug.
+
+---
+
+## 🔴 Critical Issues (Will Break Production)
+
+<!-- Issues that cause runtime failures or security vulnerabilities -->
+
+### [Issue: e.g., Server Components Can't Use useState]
+
+**Framework**: [e.g., Next.js 13+ (App Router)]
+
+**Symptom**:
+
+```
+Error: useState is not a function in Server Components
+```
+
+**Cause**: [e.g., Next.js App Router renders components on the server by default. React hooks like `useState` only work in Client Components.]
+
+**Solution**:
+
+```typescript
+// ❌ Bad: Using useState in a Server Component
+export default function Page() {
+  const [count, setCount] = useState(0) // ERROR!
+  return <div>{count}</div>
+}
+
+// ✅ Good: Add 'use client' directive
+'use client'
+
+export default function Page() {
+  const [count, setCount] = useState(0) // Works!
+  return <div>{count}</div>
+}
+```
+
+**AI Agent Note**: ⚠️ Before using `useState`, `useEffect`, or any React hook, verify the component has `'use client'` at the top of the file.
+
+**Reference**: [Link to Next.js Server Components docs]
+
+---
+
+### [Issue: e.g., Environment Variables Not Available in Browser]
+
+**Framework**: [e.g., Next.js, Vite, Create React App]
+
+**Symptom**:
+
+```
+process.env.API_KEY is undefined in the browser
+```
+
+**Cause**: [e.g., Only environment variables prefixed with `NEXT_PUBLIC_` are exposed to the browser. Others are server-only.]
+
+**Solution**:
+
+```bash
+# ❌ Bad: Not exposed to browser
+API_KEY=secret123
+
+# ✅ Good: Exposed to browser
+NEXT_PUBLIC_API_KEY=public123
+```
+
+**Security Warning**: ⚠️ NEVER prefix secrets with `NEXT_PUBLIC_`. These are exposed in the client bundle.
+
+**AI Agent Note**: When generating code that uses `process.env` in the browser, verify the variable name starts with `NEXT_PUBLIC_`.
+
+---
+
+## 🟡 Common Errors (Will Cause Confusion)
+
+<!-- Non-critical issues that are confusing but won't break production -->
+
+### [Issue: e.g., Tailwind Styles Not Applying After Config Change]
+
+**Framework**: [e.g., Tailwind CSS (JIT Mode)]
+
+**Symptom**: Added a custom color in `tailwind.config.js`, but it doesn't work in components.
+
+**Cause**: [e.g., Tailwind's JIT compiler caches build output. Config changes require a dev server restart.]
+
+**Solution**:
+
+```bash
+# Stop dev server (Ctrl+C), then restart
+pnpm dev
+```
+
+**Workaround**: [e.g., Use Tailwind's `--watch` flag for automatic reloading]
+
+**AI Agent Note**: After modifying `tailwind.config.js`, always suggest restarting the dev server.
+
+---
+
+### [Issue: e.g., TypeScript Can't Find Module After Creating It]
+
+**Framework**: [e.g., TypeScript]
+
+**Symptom**:
+
+```
+Cannot find module './myFile' or its corresponding type declarations.
+```
+
+**Cause**: [e.g., TypeScript language server cache is stale]
+
+**Solution**:
+
+```
+VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server"
+```
+
+**AI Agent Note**: If a newly created file isn't recognized, suggest restarting the TypeScript server.
+
+---
+
+## 🟢 Framework Gotchas (Non-Obvious Behavior)
+
+<!-- Quirks that aren't errors but might surprise developers -->
+
+### [Gotcha: e.g., Database Timestamps Use Different Timezone Than App]
+
+**Framework**: [e.g., PostgreSQL, Prisma]
+
+**Behavior**: [e.g., PostgreSQL `TIMESTAMP` defaults to server timezone, not UTC]
+
+**Recommendation**:
+
+```sql
+-- ❌ Bad: Uses server timezone
+createdAt TIMESTAMP DEFAULT NOW()
+
+-- ✅ Good: Explicitly use UTC
+createdAt TIMESTAMPTZ DEFAULT NOW()
+```
+
+**AI Agent Note**: Always use `TIMESTAMPTZ` (timestamp with time zone) instead of `TIMESTAMP` in PostgreSQL schemas.
+
+**Reference**: [See SCHEMA.md for timestamp rules]
+
+---
+
+### [Gotcha: e.g., Array.map() in JSX Requires Unique Keys]
+
+**Framework**: [e.g., React]
+
+**Behavior**: React throws a warning if list items don't have unique `key` props.
+
+**Recommendation**:
+
+```typescript
+// ❌ Bad: No key prop
+{users.map(user => <div>{user.name}</div>)}
+
+// ✅ Good: Stable, unique key
+{users.map(user => <div key={user.id}>{user.name}</div>)}
+
+// ⚠️ Avoid: Using array index (breaks on reorder)
+{users.map((user, index) => <div key={index}>{user.name}</div>)}
+```
+
+**AI Agent Note**: When generating `map()` in JSX, always add a `key` prop using a stable ID (not array index).
+
+---
+
+## 🛠️ Environment Setup Issues
+
+<!-- Problems that occur during installation or local development -->
+
+### [Issue: e.g., pnpm install fails with EACCES error]
+
+**Platform**: [e.g., macOS, Linux]
+
+**Symptom**:
+
+```
+Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
+```
+
+**Cause**: [e.g., npm/pnpm trying to write to system-protected directory]
+
+**Solution**:
+
+```bash
+# Use a Node version manager (nvm, fnm, volta)
+# Never use sudo with npm/pnpm
+```
+
+**AI Agent Note**: If installation fails with EACCES, recommend using a Node version manager instead of `sudo`.
+
+---
+
+### [Issue: e.g., Port 3000 already in use]
+
+**Platform**: [e.g., Any]
+
+**Symptom**:
+
+```
+Error: Port 3000 is already in use
+```
+
+**Solution**:
+
+```bash
+# Option 1: Kill process on port 3000
+lsof -ti:3000 | xargs kill -9
+
+# Option 2: Use a different port
+PORT=3001 pnpm dev
+```
+
+**AI Agent Note**: When dev server fails to start, check if another process is using the port.
+
+---
+
+## 🐛 AI Agent Common Mistakes
+
+<!-- Errors that AI coding assistants frequently make -->
+
+### [Mistake: e.g., Hallucinating Non-Existent Imports]
+
+**Example**:
+
+```typescript
+// ❌ AI might generate this (doesn't exist)
+import { useAuth } from '@/lib/auth';
+
+// ✅ Correct import (verify in codebase first)
+import { useAuth } from '@/hooks/useAuth';
+```
+
+**Prevention**: ⚠️ Before suggesting an import, verify the file/export exists in the project.
+
+**Validation**: Use `grep -r "export.*useAuth"` to find the actual export location.
+
+---
+
+### [Mistake: e.g., Using Deprecated APIs]
+
+**Example**:
+
+```typescript
+// ❌ AI might use deprecated Next.js API
+import { useRouter } from 'next/router'; // Pages Router (old)
+
+// ✅ Use App Router API (Next.js 13+)
+import { useRouter } from 'next/navigation'; // App Router (new)
+```
+
+**Prevention**: ⚠️ Check `docs/core/ARCHITECTURE.md` for the framework version before generating code.
+
+**Reference**: [See ARCHITECTURE.md for tech stack versions]
+
+---
+
+### [Mistake: e.g., Not Handling Async Errors in React]
+
+**Example**:
+
+```typescript
+// ❌ Unhandled promise rejection
+async function handleSubmit() {
+  await fetch('/api/submit'); // No error handling
+}
+
+// ✅ Proper error handling
+async function handleSubmit() {
+  try {
+    await fetch('/api/submit');
+  } catch (error) {
+    console.error('Submit failed:', error);
+    // Show user-friendly error message
+  }
+}
+```
+
+**Prevention**: ⚠️ Always wrap async operations in try/catch blocks.
+
+---
+
+## 📚 Reference Checklist (For AI Agents)
+
+Before implementing a feature, verify:
+
+- [ ] Framework version matches `docs/core/ARCHITECTURE.md`
+- [ ] Imports use correct paths (check existing files)
+- [ ] Environment variables use correct prefix (e.g., `NEXT_PUBLIC_`)
+- [ ] Database timestamps use correct type (e.g., `TIMESTAMPTZ`)
+- [ ] React components use `'use client'` when needed
+- [ ] TypeScript types match `docs/core/SCHEMA.md`
+- [ ] Error handling is implemented (no unhandled promises)
+
+---
+
+## 🔗 Related Documentation
+
+- **Architecture**: See `ARCHITECTURE.md` for framework versions
+- **Schema**: See `SCHEMA.md` for database gotchas
+- **Patterns**: See `PATTERNS.md` for anti-patterns
+
+---
+
+## 📝 How to Document a New Issue
+
+When you encounter a new gotcha:
+
+1. **Title**: Brief, searchable description (e.g., "useState in Server Components")
+2. **Framework**: Which tool/library this affects
+3. **Symptom**: Exact error message or unexpected behavior
+4. **Cause**: Why this happens
+5. **Solution**: Code example showing fix
+6. **AI Agent Note**: What to check before generating this code
+
+**Template**:
+
+```markdown
+### [Issue: Brief Description]
+
+**Framework**: [Tool/Library]
+**Symptom**: [Error message or behavior]
+**Cause**: [Why it happens]
+**Solution**: [Code example]
+**AI Agent Note**: [What to verify]
+```
+
+<!-- @cortex-tms-version 4.0.2 -->
+
+<!-- @cortex-tms-version 4.0.2 -->