@gitgov/core 1.13.0 → 2.1.0

package/README.md

@@ -6,309 +6,190 @@
 
 `@gitgov/core` is the **SDK** for the GitGovernance ecosystem. It provides a type-safe, local-first, and schema-driven API to manage identities, agents, tasks, and workflows in software projects.
 
-## 🚀 Quick Start
+## Install
 
-This example shows how to create a new task using the `BacklogAdapter`. The SDK uses dependency injection - each adapter requires its dependencies to be explicitly provided.
+```bash
+pnpm add @gitgov/core
+```
 
-_Note: This example assumes it is run inside an initialized GitGovernance project._
+## Quick Start
 
-```typescript
-import { Adapters, Store, EventBus } from "@gitgov/core";
-import type {
-  TaskRecord,
-  CycleRecord,
-  ActorRecord,
-  AgentRecord,
-} from "@gitgov/core";
-
-// Extract classes from namespaces
-const { IdentityAdapter, BacklogAdapter, WorkflowMethodologyAdapter } =
-  Adapters;
-const { RecordStore } = Store;
-const { EventBus: EventBusClass } = EventBus;
-
-// 1. Setup core infrastructure
-const eventBus = new EventBusClass();
-const actorStore = new RecordStore<ActorRecord>("actors");
-const agentStore = new RecordStore<AgentRecord>("agents");
-const taskStore = new RecordStore<TaskRecord>("tasks");
-const cycleStore = new RecordStore<CycleRecord>("cycles");
-
-// 2. Setup identity adapter
-const identity = new IdentityAdapter({
-  actorStore,
-  agentStore,
-});
+The SDK uses dependency injection. Each adapter receives its dependencies via constructor.
 
-// 3. Setup workflow methodology
-const workflowMethodology = WorkflowMethodologyAdapter.createDefault();
-
-// 4. Setup BacklogAdapter with minimal dependencies for basic task creation
-const backlogAdapter = new BacklogAdapter({
-  taskStore,
-  cycleStore,
-  identity,
-  eventBus,
-  workflowMethodologyAdapter: workflowMethodology,
-  // Optional dependencies (can be undefined for basic usage)
-  feedbackStore: undefined,
-  executionStore: undefined,
-  changelogStore: undefined,
-  feedbackAdapter: undefined,
-  executionAdapter: undefined,
-  changelogAdapter: undefined,
-  metricsAdapter: undefined,
+```typescript
+import { Adapters, Store, EventBus } from '@gitgov/core';
+import { FsRecordStore } from '@gitgov/core/fs';
+import type { TaskRecord, CycleRecord, ActorRecord, AgentRecord } from '@gitgov/core';
+
+// Infrastructure
+const eventBus = new EventBus.EventBus();
+const taskStore = new FsRecordStore<TaskRecord>({ recordType: 'tasks', projectRoot: '.' });
+const cycleStore = new FsRecordStore<CycleRecord>({ recordType: 'cycles', projectRoot: '.' });
+const actorStore = new FsRecordStore<ActorRecord>({ recordType: 'actors', projectRoot: '.' });
+const agentStore = new FsRecordStore<AgentRecord>({ recordType: 'agents', projectRoot: '.' });
+
+// Adapters compose modules
+const identity = new Adapters.IdentityAdapter({ actorStore, agentStore });
+const workflow = Adapters.WorkflowAdapter.createDefault();
+const backlog = new Adapters.BacklogAdapter({
+  taskStore, cycleStore, identity, eventBus, workflowAdapter: workflow,
 });
 
-// 5. Create a new task
-const newTaskPayload = {
-  title: "Implement user authentication",
-  priority: "high",
-  description: "Add OAuth2 integration for Google and GitHub.",
-};
-
-const taskRecord = await backlogAdapter.createTask(
-  newTaskPayload,
-  "human:project-lead" // The actor performing the action
+// Create a task
+const task = await backlog.createTask(
+  { title: 'Implement auth', priority: 'high' },
+  'human:project-lead',
 );
-
-console.log("✅ Task Created Successfully:");
-console.log({
-  id: taskRecord.id,
-  title: taskRecord.title,
-  status: taskRecord.status, // The adapter sets the default status
-});
-
-// Expected output:
-// ✅ Task Created Successfully:
-// {
-//   id: 'task:1727445600000-implement-user-authentication',
-//   title: 'Implement user authentication',
-//   status: 'draft'
-// }
 ```
 
-> **For production usage:** See the [complete setup example](../../blueprints/03_products/core/core_reference.md#quick-start) with all adapters and dependencies properly configured.
-
-## ✅ What's Implemented (v1.0)
-
-### Identity Management
-
-- **ActorRecord**: Cryptographic identities with Ed25519 keys
-- **AgentRecord**: AI agent operational manifests
-- **CRUD Operations**: Create, read, list, revoke operations
-- **Schema Validation**: JSON Schema-driven with detailed errors
-- **Performance**: Schema validation caching
-
-### Adapter Ecosystem (9/9 Adapters)
-
-- **ProjectAdapter**: Project initialization engine with 3-adapter orchestration (18 tests)
-- **BacklogAdapter**: Task and cycle lifecycle management with workflow validation (71 tests)
-- **MetricsAdapter**: Pure calculation engine for system analytics (32 tests)
-- **ChangelogAdapter**: System historian for change documentation (31 tests)
-- **ExecutionAdapter**: Audit log for work execution (13 tests)
-- **FeedbackAdapter**: Structured communication and blocking management (21 tests)
-- **IdentityAdapter**: Cryptographic identity and agent management (25 tests)
-- **WorkflowMethodologyAdapter**: Configurable workflow validation engine (51 tests)
-- **IndexerAdapter**: Local cache optimization for performance (5 tests)
-
-### Record System (8/8 Records)
-
-- **TaskRecord**: Factory and validation for task management
-- **CycleRecord**: Factory and validation for cycle organization
-- **ExecutionRecord**: Factory and validation for execution logging
-- **ChangelogRecord**: Factory and validation for changelog generation
-- **FeedbackRecord**: Factory and validation for feedback management
-- **ActorRecord**: Factory and validation for identity management
-- **AgentRecord**: Factory and validation for agent manifests
-
-### Infrastructure Modules
-
-- **Generic Store**: CRUD operations for all record types
-- **Integration Testing**: Cross-module validation framework
-- **WorkflowMethodologyAdapter**: Configurable workflow validation engine
-- **EventBusModule**: Event-driven architecture foundation with 9 event types
-- **DiagramGenerator**: Automatic Mermaid diagram generation with deduplication and data quality warnings
-- **Schema Generation Pipeline**: Automatic YAML→JSON→TypeScript transformation with build-time validation
-
-## 🏗️ Architecture
-
-The package is built with a domain-driven architecture to separate responsibilities. The public API is exposed through `Adapters`.
+## Architecture
 
 ```mermaid
-graph TD
-    subgraph "@gitgov/core"
-        PA[ProjectAdapter] --> IA[IdentityAdapter];
-        PA --> BA[BacklogAdapter];
-        PA --> WMA[WorkflowMethodologyAdapter];
-        PA --> CM[ConfigManager];
-        PA --> F((Factories));
-        IA --> F;
-        IA --> V((Validation));
-        IA --> S((Store));
-        IA --> CR((Crypto));
+graph LR
+    subgraph "@gitgov/core — Pure Logic"
+        Adapters["Adapters (10)"]
+        Modules["Modules (24)"]
+        Records["Record System"]
+
+        Adapters --> Modules
+        Adapters --> Records
+        Modules --> Records
     end
 
-    subgraph "Consumidores"
-        CLI["@gitgov/cli"]
-        SAAS["@gitgov/saas"]
+    subgraph "@gitgov/core/fs — I/O"
+        FsStore["FsRecordStore"]
+        FsGit["LocalGitModule"]
+        FsLint["FsLintModule"]
+        FsOther["FsKeyProvider, FsFileLister, ..."]
     end
 
-    CLI --> PA;
-    SAAS --> PA;
-
-    style PA fill:#e8f5e8,stroke:#4caf50,stroke-width:2px
-    style IA fill:#e8f5e8,stroke:#4caf50,stroke-width:2px
-    style BA fill:#e8f5e8,stroke:#4caf50,stroke-width:2px
-```
-
-### Core Principles
-
-1.  **Protocol-Driven**: The canonical JSON Schemas that define the governance protocol are bundled with the package and are the single source of truth for all data validation.
-2.  **Build-Time Generation**: Schemas and types are automatically generated from YAML protocols using `npm run prebuild` (pipeline) or individual commands, ensuring 100% coherence.
-3.  **Type Safety**: Strict TypeScript with no `any` to prevent compile-time errors.
-4.  **Event Coherence Guarantee**: Event payloads are derived from canonical records using TypeScript Utility Types, ensuring 100% consistency between system state and system events.
-5.  **Rich Errors**: Detailed, field-level validation errors to make debugging easier.
-6.  **Performance**: A compiled schema cache (`SchemaValidationCache`) minimizes I/O and accelerates repetitive validations.
-7.  **Local-First**: Designed to operate directly on a Git repository as its database.
+    subgraph "@gitgov/core/memory — Testing"
+        MemStore["MemoryRecordStore"]
+        MemGit["MemoryGitModule"]
+        MemOther["MockKeyProvider, MemoryFileLister"]
+    end
 
-## 🔧 Advanced Usage
+    Adapters -.->|DI| FsStore
+    Adapters -.->|DI| MemStore
 
-### Schema Validation
+    CLI["@gitgov/cli"] --> Adapters
+    SaaS["@gitgov/saas-api"] --> Adapters
 
-```typescript
-import {
-  validateActorRecordDetailed,
-  DetailedValidationError,
-} from "@gitgov/core";
-
-const result = validateActorRecordDetailed(userData);
-if (!result.isValid) {
-  result.errors.forEach((error) => {
-    console.log(`❌ ${error.field}: ${error.message}`);
-    console.log(`   Got: ${JSON.stringify(error.value)}`);
-  });
-}
+    style Adapters fill:#e8f5e8,stroke:#4caf50,stroke-width:2px
+    style FsStore fill:#e3f2fd,stroke:#1976d2
+    style MemStore fill:#fff3e0,stroke:#f57c00
 ```
 
-### Custom Error Handling
+### 3 Export Paths
+
+| Import | Contents | I/O |
+|--------|----------|-----|
+| `@gitgov/core` | Interfaces, types, pure logic, factories, validators | No |
+| `@gitgov/core/fs` | Filesystem implementations (FsRecordStore, LocalGitModule, FsLintModule, ...) | Yes |
+| `@gitgov/core/memory` | In-memory implementations for testing (MemoryRecordStore, MemoryGitModule, ...) | No |
+
+The root import (`@gitgov/core`) never imports `fs`, `path`, or `child_process`.
+
+### Record Symmetry
+
+Every record type has 4 parallel artifacts:
+
+| Artifact | Directory | Responsibility |
+|----------|-----------|----------------|
+| Types | `record_types/generated/` | Shape of the record (generated from schema) |
+| Factory | `record_factories/` | Create record with defaults + validation |
+| Validator | `record_validations/` | Business rules on the record |
+| Schema | `record_schemas/generated/` | JSON Schema for AJV validation |
+
+The 8 records: **Actor, Agent, Task, Cycle, Execution, Changelog, Feedback, Workflow**
+
+## Adapters
+
+Adapters are orchestrators that compose modules. All receive dependencies via constructor injection.
+
+| Adapter | Purpose |
+|---------|---------|
+| `ProjectAdapter` | Project initialization, environment validation |
+| `IdentityAdapter` | Actor and agent identity management |
+| `BacklogAdapter` | Task and cycle lifecycle, workflow validation |
+| `ExecutionAdapter` | Execution audit log tracking |
+| `FeedbackAdapter` | Structured feedback and blocking resolution |
+| `ChangelogAdapter` | Automatic changelog entries |
+| `MetricsAdapter` | System status and productivity metrics |
+| `IndexerAdapter` | Local cache generation and integrity checks |
+| `WorkflowAdapter` | State transitions with signatures and custom rules |
+| `AgentAdapter` | Agent lifecycle management |
+
+## Modules
+
+| Module | Responsibility |
+|--------|----------------|
+| `record_types/` | TypeScript types per record (generated from schemas) |
+| `record_factories/` | Factories with defaults for creating records |
+| `record_validations/` | Business validators (above schema) |
+| `record_schemas/` | JSON Schemas + schema cache + errors |
+| `record_store/` | `RecordStore<T>` interface (impl in fs/memory) |
+| `config_store/` | Storage for project config.json |
+| `config_manager/` | Typed access to config.json (versioned in git) |
+| `session_store/` | Storage for .session.json |
+| `session_manager/` | Typed access to .session.json (ephemeral, not versioned) |
+| `sync_state/` | Push/pull/resolve synchronization state |
+| `git/` | `IGitModule` interface + local/memory implementations |
+| `crypto/` | Checksums, digital signatures, verification |
+| `key_provider/` | Key storage abstraction (fs/memory) |
+| `file_lister/` | File listing abstraction (fs/memory) |
+| `lint/` | Structural + referential validation |
+| `event_bus/` | Typed pub/sub with 9 event types |
+| `agent_runner/` | Agent execution (interface + loader) |
+| `watcher_state/` | File change tracking in .gitgov/ |
+| `project_initializer/` | GitGovernance project setup |
+| `finding_detector/` | Finding detection (regex, heuristic, LLM) |
+| `source_auditor/` | Cross-system audit (code, Jira, gitgov) |
+| `diagram_generator/` | Mermaid diagram generation |
+| `logger/` | Centralized logging |
+| `utils/` | ID generation/parsing, array utils, signature utils |
+
+## Development
 
-```typescript
-import {
-  DetailedValidationError,
-  RecordNotFoundError,
-  ProjectRootError,
-} from "@gitgov/core";
-
-function handleCoreErrors(error: unknown) {
-  if (error instanceof DetailedValidationError) {
-    return { type: "validation", fields: error.errors };
-  } else if (error instanceof RecordNotFoundError) {
-    return { type: "not_found", code: error.code };
-  } else if (error instanceof ProjectRootError) {
-    return { type: "setup", message: "Initialize Git repository first" };
-  }
-  return { type: "unknown", error };
-}
-```
+```bash
+# Type check
+pnpm tsc --noEmit
 
-### Performance Monitoring
+# Build (full pipeline: schemas + types + tsup)
+pnpm build
 
-```typescript
-import { SchemaValidationCache } from "@gitgov/core";
+# Tests
+pnpm test
+pnpm test:coverage
+```
 
-// Monitor cache efficiency
-const stats = SchemaValidationCache.getCacheStats();
-console.log(`Cache hit ratio: ${stats.cachedSchemas} schemas loaded`);
+### Build Pipeline
 
-// Clear cache when schemas are updated
-SchemaValidationCache.clearCache();
+```
+YAML schemas -> JSON schemas (AJV) -> TypeScript types (generated/)
 ```
 
-### Diagram Generation
+Individual steps:
 
-```typescript
-import { DiagramGenerator } from "@gitgov/core";
-
-const generator = new DiagramGenerator();
+```bash
+pnpm sync                  # Sync from blueprints (schemas, configs, prompts)
+pnpm compile:types         # JSON -> TypeScript
+pnpm generate:indexes      # Generate barrel exports
+pnpm validate:schemas      # Validate all schemas
+pnpm prebuild              # compile:types + generate:indexes
+```
 
-// Generate Mermaid diagrams from GitGovernance records
-const result = await generator.generateFromRecords(cycles, tasks, {
-  cycleId: "1704067200-cycle-identity-adapter",
-  layout: "TD",
-  showWarnings: true,
-});
+Never edit files in `generated/`. Modify the source schema and regenerate.
 
-console.log(result.mermaidCode);
-// Automatic deduplication and data quality warnings included
-```
+## License
 
-## 🧪 Testing & Development
+This package is licensed under the [Mozilla Public License 2.0 (MPL-2.0)](https://opensource.org/licenses/MPL-2.0).
 
-```bash
-# Run all tests (737 tests total)
-npm test
-npm run test:coverage    # Run tests with coverage report
-
-# Build-time schema and type generation
-npm run sync:prompts           # Sync agent prompts for npm packaging
-npm run sync:schemas           # Generate JSON schemas from YAML protocols
-npm run sync:workflow-configs  # Sync workflow methodology configurations
-npm run compile:types          # Generate TypeScript types from JSON schemas
-npm run generate:indexes       # Generate organized export indexes
-npm run validate:schemas       # Validate all generated schemas
-
-# Development workflow
-npm run prebuild         # Pipeline: sync:prompts → compile:types → generate:indexes
-npm run build           # Clean build with TypeScript compilation
-npm run clean           # Remove dist directory
-npm run clean:generated # Remove all generated schemas and types
-
-# Type checking
-npx tsc --noEmit
-
-# Watch mode for development
-npm test -- --watch
-```
+## Links
 
-### Test Coverage
-
-- **737 tests total** with EARS methodology
-- **ProjectAdapter**: 18 tests (project initialization + template processing + error recovery)
-- **BacklogAdapter**: 71 tests (workflow lifecycle + event handlers + E2E simulation + deduplication)
-- **MetricsAdapter**: 32 tests (Tier 1+2 calculations + performance validation)
-- **ChangelogAdapter**: 31 tests (multi-entity changelog + conditional validation)
-- **EventBusModule**: 32 tests (20 unit + 12 integration tests with cross-adapter scenarios)
-- **FeedbackAdapter**: 21 tests (EARS coverage with dual event emission + duplicate assignment prevention)
-- **ExecutionAdapter**: 13 tests (EARS coverage with performance validation)
-- **WorkflowMethodologyAdapter**: 51 tests (29 unit + 22 integration tests)
-- **Identity Domain**: 66 tests (Adapter + ActorRecord/AgentRecord factories & validators)
-- **Validation**: 62 tests (for Task, Cycle, Exec, CL, Feedback records + schema caching)
-- **Factories**: 40 tests (for Task, Cycle, Exec, CL, Feedback records)
-- **Store**: 26 tests (generic CRUD for all record types)
-- **Crypto**: 23 tests (signatures + checksums for all 7 record types)
-- **ConfigManager**: 20 tests (configuration + session state + project utilities)
-- **IndexerAdapter**: 5 tests (cache generation, validation, and retrieval)
-- **Utils**: 10 tests (ID generation utilities)
-- **Integration**: 74 tests (cross-module validation)
-
-## 📋 Roadmap
-
-### Next Steps
-
-- **Git Adapter**: Development of a low-level adapter for direct Git operations.
-- **Platform Adapters**: Integration with platform-specific features (e.g., GitHub Adapter).
-- **Advanced Validation**: Creation of `lint` and `audit` modules for structural and protocol validation.
-
-### Recently Completed
-
-- **Adapter Ecosystem**: All 9 core adapters for the foundational domains have been implemented and tested.
-- **IndexerAdapter**: A dedicated module for local cache optimization to enhance performance is now available.
-- **EventBusModule**: The foundational event-driven architecture is in place, enabling decoupled communication between modules.
-- **ProjectAdapter**: The project initialization and orchestration logic is functional.
-- **DiagramGenerator Module**: Automatic Mermaid diagram generation with deduplication, data quality warnings, and advanced filtering.
-- **Schema Generation Pipeline**: YAML→JSON→TypeScript build-time transformation with automatic synchronization.
+- **GitHub:** https://github.com/gitgovernance/monorepo/tree/main/packages/core
+- **NPM:** https://www.npmjs.com/package/@gitgov/core
 
 ---
 
-**Built with ❤️ by the GitGovernance Team**
+**Built with ❤️ by the GitGovernance team.**