pi-harness-runtime 0.10.13 → 0.10.15

package/RFC/0044_TASK_COMPILER.md

@@ -1,207 +0,0 @@
-# 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

@@ -1,246 +0,0 @@
-# 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

@@ -1,14 +0,0 @@
-# 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

@@ -1,14 +0,0 @@
-# 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

@@ -1,14 +0,0 @@
-# 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

@@ -1,14 +0,0 @@
-# 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

@@ -1,14 +0,0 @@
-# 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

@@ -1,144 +0,0 @@
-# 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