pi-harness-runtime 0.10.11 → 0.10.13

package/IMPLEMENTATION/RFC-0037/AI_BRIEF.md

@@ -0,0 +1,59 @@
+# RFC-0037 AI Brief: Code Generation Pipeline
+
+## Summary
+
+A comprehensive code generation system with template management, validation pipeline, and automatic rollback capabilities.
+
+## Implementation Overview
+
+### Key Classes to Implement
+
+1. **CodeGenerator** (`generator.ts`)
+   - Template loading and management
+   - Variable resolution
+   - File generation
+   - Dry run/preview mode
+
+2. **TemplateManager** (`templates/manager.ts`)
+   - Template registry
+   - Template loading from filesystem
+   - EJS-based rendering
+
+3. **ValidationPipeline** (`validation/pipeline.ts`)
+   - Rule-based validation
+   - TypeScript checking
+   - ESLint validation
+   - Security scanning
+
+4. **RollbackManager** (`rollback/manager.ts`)
+   - Checkpoint creation
+   - File restoration
+   - Automatic rollback on failure
+
+5. **ChangeTracker** (`changes/tracker.ts`)
+   - Change set recording
+   - Diff generation
+   - History management
+
+### Dependencies
+
+- `packages/types` - for runtime-types
+- `ejs` - template rendering
+- `diff` - for generating file diffs
+- `fast-glob` - for file pattern matching
+
+### Files to Create
+
+- `packages/code-generation/src/generator.ts`
+- `packages/code-generation/src/templates/manager.ts`
+- `packages/code-generation/src/templates/loader.ts`
+- `packages/code-generation/src/templates/registry.ts`
+- `packages/code-generation/src/validation/pipeline.ts`
+- `packages/code-generation/src/validation/rules/`
+- `packages/code-generation/src/validation/validators/`
+- `packages/code-generation/src/rollback/manager.ts`
+- `packages/code-generation/src/rollback/snapshot.ts`
+- `packages/code-generation/src/changes/tracker.ts`
+- `packages/code-generation/src/engine/renderer.ts`
+- `packages/code-generation/src/types.ts`
+- `packages/code-generation/src/index.ts`

package/IMPLEMENTATION/RFC-0037/TASKS.md

@@ -0,0 +1,63 @@
+# RFC-0037 Implementation Tasks
+
+## Phase 1: Generator Core
+
+- [ ] Create `packages/code-generation/` directory
+- [ ] Define types (`CodeTemplate`, `GeneratedFile`, `GenerationResult`)
+- [ ] Create `CodeGenerator` class
+- [ ] Implement `generate()` method
+- [ ] Implement `preview()` (dry run) method
+
+## Phase 2: Template System
+
+- [ ] Create `TemplateManager` class
+- [ ] Implement EJS-based rendering
+- [ ] Implement `TemplateRegistry`
+- [ ] Add variable resolution
+- [ ] Create built-in templates:
+  - [ ] React component template
+  - [ ] Next.js page template
+  - [ ] API endpoint template
+
+## Phase 3: Validation Pipeline
+
+- [ ] Create `ValidationPipeline` class
+- [ ] Define `ValidationRule` interface
+- [ ] Implement built-in rules:
+  - [ ] no-typescript-errors
+  - [ ] no-unused-imports
+  - [ ] security-no-hardcoded-secrets
+- [ ] Implement TypeScript validation
+- [ ] Implement ESLint validation
+
+## Phase 4: Rollback System
+
+- [ ] Create `RollbackManager` class
+- [ ] Implement checkpoint creation
+- [ ] Implement file restoration
+- [ ] Implement `rollback()` method
+- [ ] Implement `listCheckpoints()`
+- [ ] Implement `prune()`
+
+## Phase 5: Change Tracking
+
+- [ ] Create `ChangeTracker` class
+- [ ] Implement `recordGeneration()`
+- [ ] Implement `recordRollback()`
+- [ ] Implement `getRecentChanges()`
+- [ ] Implement diff generation
+
+## Phase 6: Framework Integration
+
+- [ ] Create framework-specific templates
+- [ ] Integrate with FrameworkDetector (RFC-0038)
+- [ ] Add Frappe/ERPNext templates
+- [ ] Add Next.js templates
+- [ ] Add Django templates
+
+## Phase 7: Testing & Documentation
+
+- [ ] Write unit tests for all components
+- [ ] Create usage examples
+- [ ] Write documentation
+- [ ] Performance testing with large templates

package/IMPLEMENTATION/RFC-0038/AI_BRIEF.md

@@ -0,0 +1,67 @@
+# RFC-0038 AI Brief: Framework Detector
+
+## Summary
+
+An intelligent framework detection system that identifies project frameworks, libraries, and architectures with confidence scoring.
+
+## Implementation Overview
+
+### Key Classes to Implement
+
+1. **FrameworkDetector** (`detector.ts`)
+   - Signal-based detection
+   - Confidence scoring
+   - File scanning
+   - Package analysis
+
+2. **FrameworkSignature Registry** (`signatures/registry.ts`)
+   - Detection pattern definitions
+   - Pattern weighting
+   - Framework metadata
+
+3. **VersionDetector** (`version-detector/`)
+   - Frappe version detection
+   - Next.js version detection
+   - Django version detection
+   - Framework-specific version parsing
+
+4. **FileScanner** (`scanners/file-scanner.ts`)
+   - Directory traversal
+   - Pattern matching
+   - Caching
+
+### Supported Frameworks
+
+- Frappe/ERPNext
+- Frappe SPA
+- Next.js
+- React with Vite
+- React with CRA
+- Django
+- Laravel
+- Spring Boot
+- And more...
+
+### Dependencies
+
+- `packages/types` - for runtime-types
+- `fast-glob` - for file pattern matching
+- `chokidar` - for file watching
+
+### Files to Create
+
+- `packages/framework-detector/src/detector.ts`
+- `packages/framework-detector/src/signatures/registry.ts`
+- `packages/framework-detector/src/signatures/patterns.ts`
+- `packages/framework-detector/src/signatures/weights.ts`
+- `packages/framework-detector/src/scanners/file-scanner.ts`
+- `packages/framework-detector/src/scanners/package-scanner.ts`
+- `packages/framework-detector/src/scanners/config-scanner.ts`
+- `packages/framework-detector/src/version-detector/index.ts`
+- `packages/framework-detector/src/version-detector/frappe.ts`
+- `packages/framework-detector/src/version-detector/nextjs.ts`
+- `packages/framework-detector/src/version-detector/django.ts`
+- `packages/framework-detector/src/cache/detector-cache.ts`
+- `packages/framework-detector/src/watcher/file-watcher.ts`
+- `packages/framework-detector/src/types.ts`
+- `packages/framework-detector/src/index.ts`

package/IMPLEMENTATION/RFC-0038/TASKS.md

@@ -0,0 +1,65 @@
+# RFC-0038 Implementation Tasks
+
+## Phase 1: Detector Core
+
+- [ ] Create `packages/framework-detector/` directory
+- [ ] Define types (`FrameworkDetection`, `DetectionSignal`, etc.)
+- [ ] Create `FrameworkDetector` class
+- [ ] Implement `detect()` method
+- [ ] Implement `quickDetect()` method
+
+## Phase 2: Signatures
+
+- [ ] Create `FrameworkSignatureRegistry`
+- [ ] Define detection patterns for:
+  - [ ] Frappe/ERPNext
+  - [ ] Frappe SPA
+  - [ ] Next.js
+  - [ ] React (Vite)
+  - [ ] React (CRA)
+  - [ ] Vue.js
+  - [ ] Django
+  - [ ] Laravel
+  - [ ] Spring Boot
+  - [ ] Ruby on Rails
+- [ ] Implement pattern weighting
+
+## Phase 3: Scanners
+
+- [ ] Create `FileScanner` class
+- [ ] Implement directory traversal
+- [ ] Implement pattern matching
+- [ ] Create `PackageScanner` for package.json analysis
+- [ ] Create `ConfigScanner` for config file parsing
+- [ ] Add parallel scanning support
+
+## Phase 4: Version Detection
+
+- [ ] Create `VersionDetector` class
+- [ ] Implement Frappe version detection
+- [ ] Implement Next.js version detection
+- [ ] Implement Django version detection
+- [ ] Implement Laravel version detection
+- [ ] Add version caching
+
+## Phase 5: Caching & Watching
+
+- [ ] Create detection cache
+- [ ] Implement cache invalidation
+- [ ] Create `FileWatcher` for real-time updates
+- [ ] Implement callback-based notifications
+
+## Phase 6: Capabilities & Recommendations
+
+- [ ] Implement `FrameworkCapability` detection
+- [ ] Create `StrategyRecommendation` engine
+- [ ] Add recommended seed strategies
+- [ ] Add recommended E2E strategies
+
+## Phase 7: Testing & Documentation
+
+- [ ] Create test fixtures for each framework
+- [ ] Test detection accuracy
+- [ ] Test version detection
+- [ ] Performance testing
+- [ ] Write documentation

package/IMPLEMENTATION/RFC-0039/AI_BRIEF.md

@@ -0,0 +1,68 @@
+# RFC-0039 AI Brief: Test Data Generator
+
+## Summary
+
+A comprehensive test data generation system that creates realistic, framework-aware test data with Faker.js integration and multiple export formats.
+
+## Implementation Overview
+
+### Key Classes to Implement
+
+1. **TestDataGenerator** (`generator.ts`)
+   - Schema-based generation
+   - Bulk data creation
+   - Multiple export formats
+   - Seed support for reproducibility
+
+2. **SchemaManager** (`schema/validator.ts`)
+   - Schema validation
+   - Field type definitions
+   - Custom generator support
+
+3. **FactoryRegistry** (`factories/registry.ts`)
+   - Factory pattern for test data
+   - Default values
+   - Sequences
+   - Post-creation hooks
+
+4. **RelationHandler** (`relations/handler.ts`)
+   - Foreign key relationships
+   - One-to-many, many-to-many
+   - Referential integrity
+
+5. **FrameworkAdapters** (`adapters/`)
+   - Frappe adapter
+   - Next.js adapter
+   - Django adapter
+   - Laravel adapter
+
+### Dependencies
+
+- `packages/types` - for runtime-types
+- `@faker-js/faker` - data generation
+- `yaml` - YAML export
+- `csv-stringify` - CSV export
+
+### Files to Create
+
+- `packages/test-data-generator/src/generator.ts`
+- `packages/test-data-generator/src/schema/validator.ts`
+- `packages/test-data-generator/src/schema/parser.ts`
+- `packages/test-data-generator/src/faker/faker-adapter.ts`
+- `packages/test-data-generator/src/faker/generators.ts`
+- `packages/test-data-generator/src/factories/registry.ts`
+- `packages/test-data-generator/src/factories/builder.ts`
+- `packages/test-data-generator/src/relations/handler.ts`
+- `packages/test-data-generator/src/relations/integrity.ts`
+- `packages/test-data-generator/src/exporters/json.ts`
+- `packages/test-data-generator/src/exporters/csv.ts`
+- `packages/test-data-generator/src/exporters/sql.ts`
+- `packages/test-data-generator/src/exporters/yaml.ts`
+- `packages/test-data-generator/src/exporters/fixtures/django.ts`
+- `packages/test-data-generator/src/exporters/fixtures/laravel.ts`
+- `packages/test-data-generator/src/adapters/frappe.ts`
+- `packages/test-data-generator/src/adapters/nextjs.ts`
+- `packages/test-data-generator/src/adapters/django.ts`
+- `packages/test-data-generator/src/adapters/laravel.ts`
+- `packages/test-data-generator/src/types.ts`
+- `packages/test-data-generator/src/index.ts`

package/IMPLEMENTATION/RFC-0039/TASKS.md

@@ -0,0 +1,74 @@
+# RFC-0039 Implementation Tasks
+
+## Phase 1: Generator Core
+
+- [ ] Create `packages/test-data-generator/` directory
+- [ ] Define types (`DataSchema`, `FieldDefinition`, `GeneratedData`)
+- [ ] Create `TestDataGenerator` class
+- [ ] Implement `generate()` method
+- [ ] Implement `generateOne()` method
+
+## Phase 2: Schema System
+
+- [ ] Create `SchemaValidator` class
+- [ ] Define built-in field types
+- [ ] Implement schema parsing
+- [ ] Add validation rules
+- [ ] Create default schemas:
+  - [ ] user schema
+  - [ ] product schema
+  - [ ] order schema
+
+## Phase 3: Faker Integration
+
+- [ ] Create `FakerAdapter` class
+- [ ] Implement Faker method mapping
+- [ ] Add locale support
+- [ ] Add seed support
+- [ ] Create custom generators
+
+## Phase 4: Factory Pattern
+
+- [ ] Create `FactoryRegistry` class
+- [ ] Implement `registerFactory()`
+- [ ] Implement `create()` method
+- [ ] Implement `createMany()` method
+- [ ] Add `sequences` support
+- [ ] Add `afterCreate` hooks
+
+## Phase 5: Relations
+
+- [ ] Create `RelationHandler` class
+- [ ] Implement relation types:
+  - [ ] one-to-one
+  - [ ] one-to-many
+  - [ ] many-to-many
+- [ ] Implement referential integrity
+- [ ] Implement `generateWithRelations()`
+
+## Phase 6: Exporters
+
+- [ ] Create JSON exporter
+- [ ] Create JSONL exporter
+- [ ] Create CSV exporter
+- [ ] Create SQL exporter (INSERT statements)
+- [ ] Create YAML exporter
+- [ ] Create fixture exporters:
+  - [ ] Django fixtures
+  - [ ] Laravel factories
+  - [ ] FactoryBot (Ruby)
+
+## Phase 7: Framework Adapters
+
+- [ ] Create `FrameworkAdapter` interface
+- [ ] Implement Frappe adapter
+- [ ] Implement Next.js adapter
+- [ ] Implement Django adapter
+- [ ] Implement Laravel adapter
+
+## Phase 8: Testing & Documentation
+
+- [ ] Write unit tests
+- [ ] Create usage examples
+- [ ] Performance testing with large datasets
+- [ ] Write documentation

package/IMPLEMENTATION/RFC-0040/AI_BRIEF.md

@@ -0,0 +1,79 @@
+# RFC-0040 AI Brief: Framework Plugin SDK
+
+## Summary
+
+A comprehensive plugin SDK for extending the harness runtime with custom framework support, providers, and tooling.
+
+## Implementation Overview
+
+### Key Classes to Implement
+
+1. **PluginManager** (`manager.ts`)
+   - Plugin registration
+   - Lifecycle management (initialize, activate, deactivate)
+   - Hook system
+   - Configuration management
+
+2. **PluginLoader** (`loader.ts`)
+   - Load plugins from filesystem
+   - Load plugins from npm
+   - Validate plugin manifest
+   - Plugin sandboxing
+
+3. **PluginSandbox** (`sandbox/sandbox.ts`)
+   - Code isolation
+   - Resource limits
+   - Timeout enforcement
+   - Network/filesystem restrictions
+
+4. **HookDispatcher** (`hooks/dispatcher.ts`)
+   - Hook registration
+   - Hook execution
+   - Result aggregation
+
+### Extension Points
+
+- Framework detection extensions
+- Provider extensions
+- Generator extensions
+- Linter extensions
+- Tool extensions
+
+### Capabilities
+
+- `provider` - Custom AI provider
+- `framework` - Framework detection extension
+- `generator` - Code generator
+- `linter` - Custom linter
+- `template` - Code template
+- `validator` - Custom validator
+- `tool` - Custom tool
+- `hook` - Hook handler
+
+### Dependencies
+
+- `packages/types` - for runtime-types
+- `chokidar` - for file watching
+- `js-yaml` - for config parsing
+- `vm2` or `isolated-vm` - for sandboxing
+
+### Files to Create
+
+- `packages/framework-plugin-sdk/src/manager.ts`
+- `packages/framework-plugin-sdk/src/loader.ts`
+- `packages/framework-plugin-sdk/src/sandbox/sandbox.ts`
+- `packages/framework-plugin-sdk/src/sandbox/isolater.ts`
+- `packages/framework-plugin-sdk/src/registry/index.ts`
+- `packages/framework-plugin-sdk/src/registry/capability-registry.ts`
+- `packages/framework-plugin-sdk/src/registry/hook-registry.ts`
+- `packages/framework-plugin-sdk/src/hooks/dispatcher.ts`
+- `packages/framework-plugin-sdk/src/hooks/types.ts`
+- `packages/framework-plugin-sdk/src/config/schema.ts`
+- `packages/framework-plugin-sdk/src/config/loader.ts`
+- `packages/framework-plugin-sdk/src/extensions/framework.ts`
+- `packages/framework-plugin-sdk/src/extensions/provider.ts`
+- `packages/framework-plugin-sdk/src/extensions/generator.ts`
+- `packages/framework-plugin-sdk/src/extensions/linter.ts`
+- `packages/framework-plugin-sdk/src/extensions/tool.ts`
+- `packages/framework-plugin-sdk/src/types.ts`
+- `packages/framework-plugin-sdk/src/index.ts`

package/IMPLEMENTATION/RFC-0040/TASKS.md

@@ -0,0 +1,77 @@
+# RFC-0040 Implementation Tasks
+
+## Phase 1: Plugin Core
+
+- [ ] Create `packages/framework-plugin-sdk/` directory
+- [ ] Define plugin types (`PluginManifest`, `Plugin`, etc.)
+- [ ] Create `PluginManager` class
+- [ ] Implement `register()` method
+- [ ] Implement lifecycle methods:
+  - [ ] `initialize()`
+  - [ ] `activate()`
+  - [ ] `deactivate()`
+
+## Phase 2: Loader & Sandbox
+
+- [ ] Create `PluginLoader` class
+- [ ] Implement manifest validation
+- [ ] Implement filesystem loading
+- [ ] Create `PluginSandbox` class
+- [ ] Implement resource limits:
+  - [ ] Timeout enforcement
+  - [ ] Memory limits
+  - [ ] Network restrictions
+  - [ ] Filesystem access control
+- [ ] Implement code isolation
+
+## Phase 3: Registry
+
+- [ ] Create `PluginRegistry` class
+- [ ] Implement plugin state management
+- [ ] Create `CapabilityRegistry`
+- [ ] Implement capability checking
+
+## Phase 4: Hooks System
+
+- [ ] Create `HookDispatcher` class
+- [ ] Define hook types
+- [ ] Implement hook registration
+- [ ] Implement hook execution
+- [ ] Implement result aggregation
+- [ ] Add built-in hooks:
+  - [ ] beforeJobStart
+  - [ ] afterJobComplete
+  - [ ] beforeTaskExecute
+  - [ ] afterTaskComplete
+  - [ ] onError
+  - [ ] onFrameworkDetected
+  - [ ] beforeGenerate
+  - [ ] afterGenerate
+
+## Phase 5: Extension Points
+
+- [ ] Create `FrameworkExtension` interface
+- [ ] Create `ProviderExtension` interface
+- [ ] Create `GeneratorExtension` interface
+- [ ] Create `LinterExtension` interface
+- [ ] Create `ToolExtension` interface
+
+## Phase 6: Configuration
+
+- [ ] Create config schema validation
+- [ ] Implement `loadPluginConfig()`
+- [ ] Add per-plugin configuration
+- [ ] Implement config hot-reload
+
+## Phase 7: Plugin Examples
+
+- [ ] Create example plugin (`builtin/example-plugin/`)
+- [ ] Document plugin creation process
+- [ ] Create npm publishing guide
+
+## Phase 8: Security & Testing
+
+- [ ] Security audit of sandbox
+- [ ] Write unit tests
+- [ ] Test plugin isolation
+- [ ] Performance testing

package/IMPLEMENTATION/RFC-0041/ACCEPTANCE_CRITERIA.md

@@ -0,0 +1,8 @@
+# Acceptance Criteria — RFC-0041
+
+- Package exports a documented `compilePrompt` API.
+- All error cases use typed error codes.
+- Required sections survive compaction.
+- No credential-like value appears in persisted artifacts.
+- Generated metadata includes token estimate and source references.
+- Tests pass without network access.

package/IMPLEMENTATION/RFC-0041/AI_BRIEF.md

@@ -0,0 +1,26 @@
+# AI Brief — RFC-0041 Prompt Compiler
+
+Implement a deterministic prompt compiler. Start with pure functions and inject filesystem, clock, hashing, token estimation, policy, and redaction dependencies.
+
+Required source files:
+
+```text
+packages/prompt-compiler/src/
++-- types.ts
++-- normalize.ts
++-- section-builder.ts
++-- deduplicate.ts
++-- budget.ts
++-- validate.ts
++-- render.ts
++-- compiler.ts
++-- index.ts
+```
+
+Hard requirements:
+
+- No provider network calls.
+- No secret persistence.
+- Same semantic input must produce the same content hash.
+- Project rules and acceptance criteria cannot be compacted away.
+- Output-limit continuation must avoid repeating completed work.

package/IMPLEMENTATION/RFC-0041/FILES.md

@@ -0,0 +1,12 @@
+# Files — RFC-0041
+
+Create `packages/prompt-compiler/src/*` and `packages/prompt-compiler/test/*`.
+
+Modify runtime integration only after package tests pass:
+
+```text
+harness/loop-runtime.ts
+harness/agent-handoff.ts
+```
+
+Do not modify quota, notification, browser, or worktree packages.

package/IMPLEMENTATION/RFC-0041/TASKS.md

@@ -0,0 +1,12 @@
+# Tasks — RFC-0041
+
+1. Define public TypeScript interfaces and discriminated error codes.
+2. Implement request normalization with stable array ordering.
+3. Implement deterministic section assembly.
+4. Implement exact deduplication.
+5. Implement token-budget compaction for optional sections.
+6. Implement provider rendering profiles.
+7. Implement SHA-256 content hashing.
+8. Persist `prompt.md`, `prompt.json`, `sources.json`, and `metadata.json`.
+9. Add continuation prompt support.
+10. Add unit and integration tests.

package/IMPLEMENTATION/RFC-0041/TESTS.md

@@ -0,0 +1,12 @@
+# Tests — RFC-0041
+
+- Deterministic hash for identical input
+- Missing objective
+- Missing output contract
+- Required source missing
+- Token budget exceeded
+- Secret redaction
+- Duplicate context removal
+- Provider profile rendering
+- Continuation without repetition
+- Persistence artifact completeness

package/IMPLEMENTATION/RFC-0042/ACCEPTANCE_CRITERIA.md

@@ -0,0 +1,7 @@
+# Acceptance Criteria — RFC-0042
+
+- Context never exceeds requested budget.
+- Required items are not silently removed.
+- Sensitive contents are excluded before persistence.
+- Identical repository state produces identical compiled context.
+- OKF and source code references appear in one traceable source graph.

package/IMPLEMENTATION/RFC-0042/AI_BRIEF.md

@@ -0,0 +1,5 @@
+# AI Brief — RFC-0042 Context Compiler
+
+Build a bounded context selection engine that combines project rules, OKF knowledge, repository slices, blackboard state, test failures, and prior reports.
+
+Never dump the entire repository. Every selected item needs a source reference; every omitted item needs a reason.

package/IMPLEMENTATION/RFC-0042/FILES.md

@@ -0,0 +1,14 @@
+# Files — RFC-0042
+
+```text
+packages/context-compiler/src/
++-- types.ts
++-- collectors/
++-- policy-filter.ts
++-- scorer.ts
++-- deduplicate.ts
++-- budget.ts
++-- source-graph.ts
++-- cache.ts
++-- compiler.ts
+```

package/IMPLEMENTATION/RFC-0042/TASKS.md

@@ -0,0 +1,12 @@
+# Tasks — RFC-0042
+
+1. Define candidate, compiled item, omission, and source-graph types.
+2. Add source collectors for rules, OKF, repository, Git diff, tests, and blackboard.
+3. Add policy filter and sensitive path denial.
+4. Implement deterministic scoring.
+5. Add exact deduplication and slice merge.
+6. Fit optional items into token budget.
+7. Generate cache key from selected source hashes.
+8. Persist compiled context and omission report.
+9. Add invalidation hooks.
+10. Add tests.

package/IMPLEMENTATION/RFC-0042/TESTS.md

@@ -0,0 +1,11 @@
+# Tests — RFC-0042
+
+- Required rule inclusion
+- `.env` denial
+- Broken optional OKF link
+- Broken required source
+- Duplicate slice merge
+- Token budget
+- Cache invalidation
+- Stable ordering
+- Omission reason completeness