pi-harness-runtime 0.10.12 → 0.10.13

package/RFC/0044_TASK_COMPILER.md

@@ -0,0 +1,207 @@
+# RFC-0044 — Task Compiler
+
+Status: Draft  
+Target package: `packages/task-compiler`  
+Depends on: Compiled Requirement, Project Analyzer, Dependency Analyzer
+
+## 1. Problem
+
+A requirement is not directly executable. The runtime needs small, dependency-aware tasks with clear inputs, outputs, permissions, verification, and handoff contracts.
+
+The Task Compiler produces a deterministic task DAG from a compiled requirement and project analysis.
+
+## 2. Task contract
+
+```ts
+export interface CompiledTask {
+  id: string;
+  jobId: string;
+  title: string;
+  objective: string;
+  type:
+    | "analysis"
+    | "implementation"
+    | "test"
+    | "review"
+    | "repair"
+    | "documentation";
+  dependencies: string[];
+  filesInScope: string[];
+  expectedOutputs: TaskOutput[];
+  acceptanceCriteria: string[];
+  requiredCapabilities: string[];
+  permittedCommands: string[];
+  prohibitedCommands: string[];
+  preferredProvider?: ProviderTarget;
+  estimatedComplexity: 1 | 2 | 3 | 5 | 8;
+}
+```
+
+## 3. Decomposition policy
+
+A task should be split when:
+
+- It requires different agent capabilities.
+- It spans unrelated modules.
+- It cannot be verified with one coherent test set.
+- It mixes destructive operations with ordinary edits.
+- It is estimated above the configured complexity threshold.
+- It has outputs that can proceed independently.
+
+A task should not be split solely to increase task count.
+
+## 4. Standard engineering flow
+
+```text
+analyze
+ -> design or schema check
+ -> implement
+ -> unit test
+ -> E2E test when applicable
+ -> review
+ -> repair if failed
+ -> documentation
+```
+
+The Task Compiler may omit stages only when project policy explicitly allows it.
+
+## 5. Dependency graph
+
+The compiler must reject cycles.
+
+```ts
+export interface TaskGraph {
+  jobId: string;
+  tasks: CompiledTask[];
+  roots: string[];
+  terminalTasks: string[];
+}
+```
+
+Topological order must be reproducible. When multiple tasks are ready, order by:
+
+1. Explicit priority
+2. Dependency depth
+3. Task ID
+
+## 6. File ownership
+
+Parallel implementation tasks must not modify overlapping files unless the Worktree and Merge Engine explicitly support it.
+
+```ts
+export interface FileOwnership {
+  taskId: string;
+  include: string[];
+  exclude: string[];
+  mode: "exclusive" | "shared_read";
+}
+```
+
+An overlap detected between exclusive scopes causes compilation failure or forced serialization.
+
+## 7. Command policy
+
+Commands are generated from project rules and task type.
+
+Example:
+
+```json
+{
+  "permittedCommands": [
+    "bun test packages/task-compiler"
+  ],
+  "prohibitedCommands": [
+    "git commit",
+    "bench migrate",
+    "bench build"
+  ]
+}
+```
+
+This respects the user's standing rule that build, migrate, and commit require permission.
+
+## 8. Verification contract
+
+Each task must define how completion is proven.
+
+```ts
+export interface TaskOutput {
+  kind: "file" | "test_result" | "report" | "schema" | "diff";
+  path?: string;
+  description: string;
+  required: boolean;
+}
+```
+
+A task cannot transition to done merely because an agent says it is complete. Required outputs must exist and verification checks must pass.
+
+## 9. Provider routing hints
+
+The Task Compiler may recommend providers but must not enforce provider availability.
+
+Example routing:
+
+- Master planning and final review: Codex/GPT
+- Broad code implementation: MiniMax
+- Debugging or alternate review: GLM
+- Browser E2E: agent with Playwright capability
+
+The Provider Router makes the final decision using quota and capability status.
+
+## 10. Reference algorithm
+
+```ts
+export function compileTasks(input: TaskCompileInput): TaskGraph {
+  const candidates = decomposeRequirement(
+    input.requirement,
+    input.project,
+    input.dependencies,
+  );
+
+  const normalized = candidates.map(candidate =>
+    applyProjectRules(
+      assignVerification(
+        assignFileScope(candidate, input.project),
+        input.requirement.acceptanceCriteria,
+      ),
+      input.project.rules,
+    ),
+  );
+
+  const graph = buildGraph(normalized);
+  assertNoCycles(graph);
+  assertNoExclusiveFileOverlap(graph);
+  assertEveryTaskHasVerification(graph);
+  return graph;
+}
+```
+
+## 11. Failure cases
+
+- Cyclic task dependencies
+- Missing verification
+- Empty objective
+- Exclusive file overlap in parallel tasks
+- Required capability unavailable in all registered workers
+- Destructive command permitted without approval gate
+- Acceptance criterion not assigned to any task
+
+## 12. Tests
+
+1. Simple requirement produces analysis, implementation, test, review.
+2. Cyclic dependencies fail.
+3. Overlapping exclusive file scopes serialize or fail.
+4. Every acceptance criterion maps to a task.
+5. Build/migrate/commit remain prohibited by default.
+6. E2E task is inserted for browser workflows.
+7. Provider preference does not become a hard dependency.
+8. Graph ordering is deterministic.
+
+## 13. Acceptance criteria
+
+- Generated graph is acyclic.
+- Every task has measurable completion outputs.
+- Every requirement criterion maps to at least one task.
+- Parallel tasks do not have unsafe file overlap.
+- Project command policy is preserved.
+- Provider routing remains advisory.

package/RFC/0045_PROJECT_ANALYZER.md

@@ -0,0 +1,246 @@
+# RFC-0045 — Project Analyzer
+
+Status: Draft  
+Target package: `packages/project-analyzer`  
+Depends on: Workspace Manager, Framework Plugin SDK
+
+## 1. Problem
+
+The runtime must understand the target repository before planning work. It needs to know project type, languages, package managers, test commands, entry points, repository rules, framework conventions, and risk areas.
+
+The Project Analyzer creates a versioned `ProjectProfile`.
+
+## 2. Output model
+
+```ts
+export interface ProjectProfile {
+  repositoryRoot: string;
+  repositoryName: string;
+  revision: string;
+  frameworks: DetectedFramework[];
+  languages: DetectedLanguage[];
+  packageManagers: PackageManagerProfile[];
+  applications: ApplicationProfile[];
+  commands: ProjectCommands;
+  rules: ProjectRule[];
+  sensitivePaths: string[];
+  generatedPaths: string[];
+  testCapabilities: TestCapability[];
+  confidence: number;
+  warnings: ProjectWarning[];
+  analyzedAt: string;
+}
+```
+
+## 3. Detection signals
+
+Examples:
+
+### Frappe / ERPNext
+
+- `sites/`
+- `apps/`
+- `hooks.py`
+- `doctype/`
+- `bench` executable or configuration
+
+### Frappe SPA
+
+- Frappe app directory
+- `frontend/`
+- Vite configuration
+- Frappe API calls
+
+### Next.js
+
+- `next.config.*`
+- `app/` or `pages/`
+- `next` dependency
+
+### React / Vite
+
+- `vite.config.*`
+- `src/main.tsx`
+- `index.html`
+
+### Django
+
+- `manage.py`
+- settings module
+- Django dependency
+
+### Laravel
+
+- `artisan`
+- `composer.json`
+- `database/seeders`
+
+Signals are weighted. A single file must not automatically establish full confidence.
+
+## 4. Multi-application repositories
+
+The analyzer must support monorepos and Frappe benches containing multiple apps.
+
+```ts
+export interface ApplicationProfile {
+  id: string;
+  root: string;
+  framework: string;
+  packageManager?: string;
+  testCommands: string[];
+  buildCommands: string[];
+  entryPoints: string[];
+}
+```
+
+The Master Planner can scope a job to one application rather than the repository root.
+
+## 5. Rule discovery
+
+The analyzer searches for:
+
+- `AGENTS.md`
+- `RULES.md`
+- `PROJECT_RULES.md`
+- `CONTRIBUTING.md`
+- package scripts
+- test configuration
+- lint configuration
+- repository-local harness configuration
+
+Rules are categorized as mandatory or advisory. Explicit user rules override inferred framework conventions.
+
+## 6. Command discovery
+
+Commands are discovered but not executed during analysis.
+
+```ts
+export interface ProjectCommands {
+  unitTest: string[];
+  integrationTest: string[];
+  e2eTest: string[];
+  lint: string[];
+  typecheck: string[];
+  build: string[];
+  migrate: string[];
+}
+```
+
+Because the user prohibits build, migrate, and commit without permission, discovery records these commands but Policy Engine blocks execution until approved.
+
+## 7. Sensitive and generated paths
+
+Typical sensitive paths:
+
+```text
+.env
+.env.*
+sites/*/site_config.json
+private/
+credentials/
+*.pem
+```
+
+Typical generated paths:
+
+```text
+node_modules/
+dist/
+build/
+public/frontend/
+coverage/
+```
+
+Framework plugins may add patterns. The analyzer must never read secret file contents merely to classify them.
+
+## 8. Confidence
+
+```text
+confidence =
+  matched_signal_weight
+  / total_required_signal_weight
+```
+
+Confidence is reported per detected framework and globally. Conflicting signals produce warnings rather than silent selection.
+
+Example:
+
+```json
+{
+  "framework": "frappe_spa",
+  "confidence": 0.94,
+  "signals": [
+    "hooks.py",
+    "frontend/vite.config.ts",
+    "frappe API imports"
+  ]
+}
+```
+
+## 9. Cache and invalidation
+
+Project analysis is cached by:
+
+- Git revision
+- Hash of rule files
+- Hash of package manifests
+- Hash of framework configuration files
+
+Source code changes that do not affect these inputs do not require full re-analysis.
+
+## 10. Plugin interface
+
+```ts
+export interface FrameworkAnalyzerPlugin {
+  id: string;
+  detect(fs: ReadonlyFileSystem): Promise<DetectionResult>;
+  analyze(
+    root: string,
+    detection: DetectionResult,
+  ): Promise<Partial<ProjectProfile>>;
+}
+```
+
+Plugins must not execute arbitrary project scripts during detection.
+
+## 11. Failure handling
+
+- Unknown framework: produce generic profile.
+- Conflicting package managers: report warning.
+- Missing test scripts: report unavailable capability.
+- Unreadable rule file: fail if mandatory, warn otherwise.
+- Repository larger than scan limit: use bounded traversal.
+- Symlink escaping repository root: reject traversal.
+
+## 12. Security
+
+The analyzer must:
+
+- Stay inside repository root.
+- Avoid following external symlinks.
+- Apply maximum file size and traversal limits.
+- Never execute detected scripts.
+- Never include secrets in `ProjectProfile`.
+- Preserve only paths and metadata for sensitive files.
+
+## 13. Tests
+
+1. Detect Frappe bench.
+2. Detect Frappe SPA.
+3. Detect Next.js.
+4. Detect React/Vite.
+5. Return generic profile for unknown project.
+6. Handle monorepo applications.
+7. Discover `AGENTS.md` rules.
+8. Record but do not execute build/migrate commands.
+9. Reject symlink traversal outside root.
+10. Cache invalidates when rule files change.
+
+## 14. Acceptance criteria
+
+- Framework detection includes confidence and evidence.
+- Multi-app repositories are represented.
+- Project rules are discoverable and prioritized.
+- Sensitive file contents are never read into output.
+- Commands are detected but not executed.
+- Generic fallback permits planning for unknown frameworks.

package/RFC/0046_DEPENDENCY_ANALYZER.md

@@ -0,0 +1,14 @@
+# RFC-0046 DEPENDENCY_ANALYZER
+
+Purpose
+- Define subsystem
+
+Interface
+```ts
+export interface Service{run(input:unknown):Promise<unknown>;}
+```
+
+Algorithm
+1.Validate
+2.Execute
+3.Emit events

package/RFC/0047_REPOSITORY_KNOWLEDGE_GRAPH.md

@@ -0,0 +1,14 @@
+# RFC-0047 REPOSITORY_KNOWLEDGE_GRAPH
+
+Purpose
+- Define subsystem
+
+Interface
+```ts
+export interface Service{run(input:unknown):Promise<unknown>;}
+```
+
+Algorithm
+1.Validate
+2.Execute
+3.Emit events

package/RFC/0048_CODE_MERGE_ENGINE.md

@@ -0,0 +1,14 @@
+# RFC-0048 CODE_MERGE_ENGINE
+
+Purpose
+- Define subsystem
+
+Interface
+```ts
+export interface Service{run(input:unknown):Promise<unknown>;}
+```
+
+Algorithm
+1.Validate
+2.Execute
+3.Emit events

package/RFC/0049_CONFLICT_RESOLUTION_ENGINE.md

@@ -0,0 +1,14 @@
+# RFC-0049 CONFLICT_RESOLUTION_ENGINE
+
+Purpose
+- Define subsystem
+
+Interface
+```ts
+export interface Service{run(input:unknown):Promise<unknown>;}
+```
+
+Algorithm
+1.Validate
+2.Execute
+3.Emit events

package/RFC/0050_DOCUMENTATION_GENERATOR.md

@@ -0,0 +1,14 @@
+# RFC-0050 DOCUMENTATION_GENERATOR
+
+Purpose
+- Define subsystem
+
+Interface
+```ts
+export interface Service{run(input:unknown):Promise<unknown>;}
+```
+
+Algorithm
+1.Validate
+2.Execute
+3.Emit events

package/RFC/0051_CAPABILITY_REGISTRY.md

@@ -0,0 +1,144 @@
+# RFC-0051 — Capability Registry
+
+Status: Draft  
+Target package: `packages/capability-registry`  
+Depends on: RFC-0053 Model Registry
+
+## 1. Problem
+
+The runtime needs to know which capabilities each model and provider supports. Currently, capabilities are hardcoded. The Capability Registry provides a centralized, extensible system for tracking and querying model capabilities.
+
+## 2. Capability Types
+
+```ts
+export type Capability =
+  | "code_generation"
+  | "code_review"
+  | "planning"
+  | "test_generation"
+  | "e2e_testing"
+  | "refactoring"
+  | "analysis"
+  | "debugging"
+  | "documentation"
+  | "vision"
+  | "function_calling"
+  | "json_mode"
+  | "streaming";
+
+export interface CapabilityProfile {
+  capability: Capability;
+  score: number; // 0-100, quality rating
+  latency: "fast" | "medium" | "slow";
+  contextWindow: number;
+  maxOutputTokens: number;
+}
+```
+
+## 3. Registry Interface
+
+```ts
+export interface CapabilityRegistry {
+  register(providerId: string, modelId: string, capabilities: CapabilityProfile[]): void;
+  unregister(providerId: string, modelId: string): void;
+  getCapabilities(providerId: string, modelId: string): CapabilityProfile[];
+  query(capability: Capability, requirements?: CapabilityQuery): ModelWithCapability[];
+  listProviders(): string[];
+  listModels(providerId: string): string[];
+}
+
+export interface CapabilityQuery {
+  minScore?: number;
+  maxLatency?: "fast" | "medium" | "slow";
+  requiresContextWindow?: number;
+  requiresMaxOutput?: number;
+}
+
+export interface ModelWithCapability {
+  providerId: string;
+  modelId: string;
+  profile: CapabilityProfile;
+}
+```
+
+## 4. Default Capabilities
+
+```ts
+export const DEFAULT_CAPABILITIES: Record<string, Record<string, CapabilityProfile[]>> = {
+  "openai": {
+    "gpt-4o": [
+      { capability: "code_generation", score: 95, latency: "medium", contextWindow: 128000, maxOutputTokens: 16384 },
+      { capability: "code_review", score: 90, latency: "medium", contextWindow: 128000, maxOutputTokens: 16384 },
+      { capability: "vision", score: 95, latency: "medium", contextWindow: 128000, maxOutputTokens: 16384 },
+      { capability: "function_calling", score: 95, latency: "medium", contextWindow: 128000, maxOutputTokens: 16384 },
+    ],
+  },
+  "anthropic": {
+    "claude-sonnet-4": [
+      { capability: "code_generation", score: 95, latency: "fast", contextWindow: 200000, maxOutputTokens: 8192 },
+      { capability: "code_review", score: 95, latency: "fast", contextWindow: 200000, maxOutputTokens: 8192 },
+      { capability: "planning", score: 90, latency: "fast", contextWindow: 200000, maxOutputTokens: 8192 },
+      { capability: "vision", score: 90, latency: "fast", contextWindow: 200000, maxOutputTokens: 8192 },
+    ],
+    "claude-opus-4": [
+      { capability: "code_generation", score: 98, latency: "slow", contextWindow: 200000, maxOutputTokens: 8192 },
+      { capability: "planning", score: 95, latency: "slow", contextWindow: 200000, maxOutputTokens: 8192 },
+      { capability: "analysis", score: 95, latency: "slow", contextWindow: 200000, maxOutputTokens: 8192 },
+    ],
+  },
+  "minimax": {
+    "MiniMax-Text-01": [
+      { capability: "code_generation", score: 85, latency: "fast", contextWindow: 1000000, maxOutputTokens: 8192 },
+      { capability: "function_calling", score: 80, latency: "fast", contextWindow: 1000000, maxOutputTokens: 8192 },
+    ],
+  },
+};
+```
+
+## 5. Query Algorithm
+
+```ts
+export function queryCapabilities(
+  registry: CapabilityRegistry,
+  capability: Capability,
+  requirements?: CapabilityQuery,
+): ModelWithCapability[] {
+  const all = registry.getAllModelsWithCapability(capability);
+  
+  return all
+    .filter(m => {
+      if (requirements?.minScore && m.profile.score < requirements.minScore) return false;
+      if (requirements?.maxLatency && LATENCY_RANK[m.profile.latency] > LATENCY_RANK[requirements.maxLatency]) return false;
+      if (requirements?.requiresContextWindow && m.profile.contextWindow < requirements.requiresContextWindow) return false;
+      if (requirements?.requiresMaxOutput && m.profile.maxOutputTokens < requirements.requiresMaxOutput) return false;
+      return true;
+    })
+    .sort((a, b) => b.profile.score - a.profile.score);
+}
+
+const LATENCY_RANK = { fast: 1, medium: 2, slow: 3 };
+```
+
+## 6. Integration Points
+
+- Provider Router uses Capability Registry to filter candidates
+- Cost Optimizer uses capability profiles for model selection
+- Task Compiler uses capabilities for task-to-model matching
+
+## 7. Events
+
+```ts
+type CapabilityRegistryEvent =
+  | { type: "capability.registered"; providerId: string; modelId: string; count: number }
+  | { type: "capability.unregistered"; providerId: string; modelId: string }
+  | { type: "capability.queried"; capability: Capability; results: number };
+```
+
+## 8. Acceptance Criteria
+
+- Registry can register/unregister capabilities
+- Query returns models sorted by score
+- Latency and context window filters work correctly
+- Default capabilities are loaded on initialization
+- Events are emitted for all mutations
+- Unit tests cover all query scenarios