pi-harness-runtime 0.10.13 → 0.10.15

package/RFC/0070_OPENAI_CODEX_ADAPTER.md

@@ -1,134 +0,0 @@
-# RFC-0070 — OpenAI Codex Adapter
-
-## Summary
-
-Integrates OpenAI's [Codex](https://openai.com/index/introducing-codex/) models as a provider for the pi-harness runtime. Codex is a specialized code model that excels at autonomous software engineering tasks — code generation, editing, navigation, and execution.
-
-## Architecture
-
-```
-packages/codex-adapter/
-+-- src/
-|   +-- provider.ts        # CodexProvider (implements ProviderExtension)
-|   +-- tools.ts           # Codex tool definitions (read, write, execute, browse)
-|   +-- executor.ts        # Code execution sandbox
-|   +-- types.ts
-|   +-- index.ts
-+-- package.json
-+-- README.md
-```
-
-## Why Codex
-
-OpenAI Codex is optimized for:
-
-- Autonomous code generation and editing
-- Codebase navigation and reasoning
-- Multi-step software engineering tasks
-- CLI tool use (`Bash`, `Edit`, `Read`, `Write`, `WebSearch`)
-
-## Provider Implementation
-
-```typescript
-// src/provider.ts
-export class CodexProvider implements ProviderExtension {
-  readonly capability = "provider";
-  readonly id = "codex";
-  readonly name = "OpenAI Codex";
-
-  constructor(config: CodexConfig);
-
-  // Invoke Codex model
-  async complete(prompt: string, options?: CodexOptions): Promise<CodexResponse>;
-
-  // Stream responses
-  stream(prompt: string, options?: CodexOptions): AsyncGenerator<string>;
-
-  // Health check
-  async healthCheck(): Promise<boolean>;
-
-  // Cost estimation
-  estimateCost(inputTokens: number, outputTokens: number): number;
-}
-```
-
-## Config
-
-```typescript
-export interface CodexConfig {
-  apiKey: string;                    // OpenAI API key
-  model?: "gpt-4o" | "o3" | "o4-mini"; // Default: gpt-4o
-  baseUrl?: string;                 // For proxies/self-hosted
-  maxTokens?: number;
-  temperature?: number;
-  tools?: CodexTool[];
-  toolChoice?: "auto" | "none";
-}
-
-export const DEFAULT_TOOLS: CodexTool[] = [
-  { type: "function", name: "Read", description: "Read file contents" },
-  { type: "function", name: "Write", description: "Write/edit file" },
-  { type: "function", name: "Bash", description: "Execute shell command" },
-  { type: "function", name: "WebSearch", description: "Search the web" },
-];
-```
-
-## Tools as Harness Capabilities
-
-Each Codex tool maps to a harness capability:
-
-| Codex Tool | Harness Capability | Description |
-|------------|-------------------|-------------|
-| `Read` | `tool.read_file` | Read any file from workspace |
-| `Write` | `tool.write_file` | Write/edit files in workspace |
-| `Bash` | `tool.execute` | Run shell commands |
-| `WebSearch` | `tool.search` | Web search for context |
-
-## Codex as Model Provider
-
-```typescript
-// Integrate with model-registry
-import { CodexProvider } from '@pi/codex-adapter';
-
-const provider = new CodexProvider({ apiKey: process.env.OPENAI_API_KEY! });
-modelRegistry.register('codex', provider);
-
-// Use in harness
-const result = await modelRegistry.invoke('codex', {
-  prompt: 'Refactor the auth module to use JWT',
-  context: { workspace: '/path/to/project' }
-});
-```
-
-## Execution Sandbox
-
-```typescript
-// src/executor.ts
-export class ExecutionSandbox {
-  constructor(config?: SandboxConfig);
-
-  // Execute code with resource limits
-  async execute(code: string, language: string): Promise<ExecutionResult>;
-
-  // Execute with file system access
-  async executeWithFS(
-    code: string,
-    language: string,
-    workspace: string
-  ): Promise<ExecutionResult>;
-
-  // Kill running process
-  kill(processId: string): void;
-}
-```
-
-## Acceptance Criteria
-
-- [ ] `CodexProvider` implements `ProviderExtension` interface
-- [ ] `complete()` calls OpenAI API with Codex tools
-- [ ] `stream()` yields partial responses
-- [ ] `healthCheck()` validates API key
-- [ ] `estimateCost()` calculates cost from token counts
-- [ ] Codex tools map to harness capabilities
-- [ ] Execution sandbox limits resource usage
-- [ ] Unit tests for provider and tools

package/RFC/0071_REQUIREMENT_INTAKE.md

@@ -1,95 +0,0 @@
-# RFC-0071 — Requirement Intake
-
-## Summary
-
-Captures and structures requirements from natural language, GitHub issues, or structured input into typed `Requirement` objects ready for downstream planning systems.
-
-## Motivation
-
-Agents need a consistent way to convert informal requests into structured requirements with priority, effort estimates, and dependency metadata — without requiring a human to fill out a template.
-
-## Architecture
-
-```
-User Input (text, GitHub issue, PR description)
-        v
-+---------------------+
-|  RequirementParser  |  -> Extracts title, description, tags, priority
-+---------------------+
-        v
-+---------------------+
-| RequirementClassifier|  -> Labels type: feature, bug, chore, spike
-+---------------------+
-        v
-+---------------------+
-| EffortEstimator     |  -> Tags effort: XS, S, M, L, XL (story points)
-+---------------------+
-        v
-    Requirement[]
-```
-
-## Types
-
-```ts
-export type RequirementType = "feature" | "bug" | "chore" | "spike" | "research";
-export type EffortLevel = "XS" | "S" | "M" | "L" | "XL";
-export type Priority = "critical" | "high" | "medium" | "low";
-
-export interface Requirement {
-  id: string;
-  type: RequirementType;
-  title: string;
-  description: string;
-  priority: Priority;
-  effort: EffortLevel;
-  tags: string[];
-  dependencies: string[];       // IDs of blocking requirements
-  acceptanceCriteria: string[];
-  source?: string;             // e.g. "GitHub Issue #42"
-  raw?: string;                // Original input
-}
-
-export interface RequirementIntakeOptions {
-  strict?: boolean;            // Reject ambiguous input vs. guess
-  defaultPriority?: Priority;
-  maxDescriptionLength?: number;
-}
-```
-
-## Core Functions
-
-### `parse(text, options?)`
-Parses raw text into a `Requirement`. Uses keyword detection for type and priority cues.
-
-### `parseBatch(texts, options?)`
-Processes multiple inputs in parallel.
-
-### `classify(requirement)`
-Infers `RequirementType` from content analysis.
-
-### `estimateEffort(requirement)`
-Tags effort level based on description complexity heuristics.
-
-### `addDependency(requirement, dependsOnId)`
-Adds a dependency relationship. Validates no cycles.
-
-## Events
-
-| Event | Payload |
-|-------|---------|
-| `requirement.parsed` | `{ requirement }` |
-| `requirement.classified` | `{ requirement }` |
-| `requirement.classification.conflict` | `{ requirement, suggested }` |
-
-## Dependencies
-
-- `@pi-harness/capability-registry` — for capability-based requirements
-- `@pi-harness/memory-engine` — for context from previous sessions
-
-## Acceptance Criteria
-
-- [ ] Parses natural language into typed Requirement
-- [ ] Keyword detection for type and priority
-- [ ] Batch parsing for issue triage
-- [ ] Cycle detection in dependencies
-- [ ] Unit tests with >80% coverage

package/RFC/0072_PROJECT_BOOTSTRAP.md

@@ -1,82 +0,0 @@
-# RFC-0072 — Project Bootstrap
-
-## Summary
-
-Creates a complete project scaffold from a typed `ProjectSpec` — repos, directories, config files, CI/CD, and initial documentation — based on a framework detection result.
-
-## Motivation
-
-Agents need to scaffold new projects reliably without manual setup. Bootstrap reads a project spec and generates the complete directory structure, config files, and initial state.
-
-## Types
-
-```ts
-export type ProjectType = "monorepo" | "single-package" | "multi-package";
-
-export interface ProjectSpec {
-  name: string;
-  type: ProjectType;
-  description?: string;
-  author?: string;
-  license?: string;
-  frameworks: string[];                    // e.g. ["frappe", "nextjs"]
-  packages?: { name: string; type: string }[];
-  features?: {
-    ci?: boolean;
-    cd?: boolean;
-    testing?: boolean;
-    typescript?: boolean;
-    eslint?: boolean;
-    prettier?: boolean;
-    docs?: boolean;
-  };
-  gitInit?: boolean;
-}
-
-export interface BootstrapResult {
-  root: string;
-  files: string[];
-  packages: string[];
-  duration: number;
-}
-```
-
-## Core Functions
-
-### `bootstrap(spec, targetDir, options?)`
-Creates project scaffold. Returns `BootstrapResult`.
-
-### `detectFrameworkAndSuggest(root)`
-Runs framework detection and suggests a default spec.
-
-### `validateSpec(spec)`
-Returns validation errors for an invalid spec.
-
-### `applyTemplate(template, spec)`
-Applies a named template (e.g. "node-typescript", "frappe-app") to a spec.
-
-## Templates
-
-Templates are defined in `src/templates/`:
-- `minimal` — bare project with package.json
-- `node-typescript` — Node + TypeScript + ESLint + Jest
-- `monorepo` — npm workspaces + Turborepo
-- `frappe-app` — Frappe app structure with modules, doctypes, web pages
-- `nextjs-app` — Next.js App Router with shadcn/ui
-
-## Events
-
-| Event | Payload |
-|-------|---------|
-| `bootstrap.started` | `{ spec }` |
-| `bootstrap.file.created` | `{ path, template }` |
-| `bootstrap.completed` | `{ result }` |
-| `bootstrap.error` | `{ error, phase }` |
-
-## Acceptance Criteria
-
-- [ ] Creates project from ProjectSpec
-- [ ] Framework detection suggests appropriate template
-- [ ] Template override works
-- [ ] Dry-run mode shows what would be created
-- [ ] Unit tests for each template

package/RFC/0073_ARCHITECTURE_GENERATOR.md

@@ -1,85 +0,0 @@
-# RFC-0073 — Architecture Generator
-
-## Summary
-
-Generates architecture documentation (Mermaid diagrams, README sections, decision records) from a project analysis and a set of architectural decisions.
-
-## Motivation
-
-Agents need to produce readable, visual architecture docs without manual effort. The generator reads a project structure and outputs ASCII/Mermaid diagrams and ADR (Architecture Decision Records).
-
-## Types
-
-```ts
-export type DiagramType = "component" | "flow" | "sequence" | "er" | "class";
-
-export interface ArchitectureDiagram {
-  type: DiagramType;
-  title: string;
-  mermaid: string;
-  description?: string;
-}
-
-export interface ArchitectureSection {
-  title: string;
-  level: 1 | 2 | 3;
-  content: string;
-  diagrams: ArchitectureDiagram[];
-}
-
-export interface DecisionRecord {
-  id: string;
-  date: string;
-  status: "proposed" | "accepted" | "deprecated" | "superseded";
-  title: string;
-  context: string;
-  decision: string;
-  consequences: string;
-  alternatives: string[];
-  supersedes?: string;
-}
-
-export interface ArchitectureOutput {
-  readme: ArchitectureSection[];
-  diagrams: ArchitectureDiagram[];
-  decisions: DecisionRecord[];
-}
-```
-
-## Core Functions
-
-### `generateFromAnalysis(analysis, options?)`
-Takes a `ProjectAnalysis` from `@pi-harness/framework-detector` and produces architecture output.
-
-### `generateDiagram(type, data)`
-Creates a Mermaid diagram string from structured data.
-
-### `generateADR(decision, context)`
-Creates an Architecture Decision Record.
-
-### `generateReadmeSection(analysis, level)`
-Generates an architecture README section.
-
-## Mermaid Templates
-
-```
-component: Component architecture (apps, modules, layers)
-flow:      Request/response flow
-sequence:  API sequence diagrams
-er:        Entity-relationship (database schema)
-class:     Type/class relationships
-```
-
-## Dependencies
-
-- `@pi-harness/framework-detector` — for project analysis
-- `@pi-harness/memory-engine` — for existing ADRs
-
-## Acceptance Criteria
-
-- [ ] Generates Mermaid component diagrams from project structure
-- [ ] Generates flow diagrams from API routes
-- [ ] Produces ADR format from decisions
-- [ ] README sections at configurable heading levels
-- [ ] Mermaid syntax validation
-- [ ] Unit tests

package/RFC/0074_SPRINT_PLANNER.md

@@ -1,61 +0,0 @@
-# RFC-0074 — Sprint Planner
-
-## Summary
-
-Organizes requirements into sprints using velocity-based estimation, capacity planning, and dependency ordering.
-
-## Motivation
-
-Agents need to plan sprints from a backlog — assigning items to sprints based on story points, team capacity, and dependencies.
-
-## Types
-
-```ts
-export interface Sprint {
-  id: string;
-  number: number;
-  name: string;
-  startDate: string;
-  endDate: string;
-  capacity: number;        // Total story points
-  items: SprintItem[];
-  status: "planning" | "active" | "completed";
-}
-
-export interface SprintItem {
-  requirementId: string;
-  title: string;
-  storyPoints: number;
-  assignee?: string;
-  status: "todo" | "in-progress" | "done";
-}
-
-export interface SprintPlanOptions {
-  sprintDurationDays: number;
-  velocity: number;           // Historical avg story points per sprint
-  startDate: string;
-  minSprintItems?: number;
-}
-```
-
-## Core Functions
-
-### `planSprints(requirements, options)`
-Distributes requirements across sprints. Respects dependencies.
-
-### `calculateVelocity(history)`
-Computes average velocity from past sprint data.
-
-### `balanceSprint(sprint, options)`
-Rebalances items in a sprint to fit capacity.
-
-### `estimateCompletion(requirements, velocity)`
-Predicts how many sprints needed to complete all items.
-
-## Acceptance Criteria
-
-- [ ] Distributes items across sprints respecting capacity
-- [ ] Respects dependency ordering (blocked items come later)
-- [ ] Velocity-based estimation
-- [ ] Sprint date range calculation
-- [ ] Unit tests

package/RFC/0075_MILESTONE_MANAGER.md

@@ -1,58 +0,0 @@
-# RFC-0075 — Milestone Manager
-
-## Summary
-
-Tracks milestones (releases, phases, deadlines) against sprint progress and alerts when items are at risk.
-
-## Motivation
-
-Agents and humans need to know if a milestone is on track, at risk, or missed — based on sprint velocity and remaining work.
-
-## Types
-
-```ts
-export type MilestoneStatus = "on-track" | "at-risk" | "missed" | "completed";
-
-export interface Milestone {
-  id: string;
-  title: string;
-  targetDate: string;
-  description?: string;
-  linkedRequirementIds: string[];
-  status: MilestoneStatus;
-  completion: number;      // 0-100
-  blockers: string[];
-}
-
-export interface MilestoneHealth {
-  milestone: Milestone;
-  onTrackItems: number;
-  totalItems: number;
-  daysRemaining: number;
-  dailyCapacityNeeded: number;
-  riskLevel: "low" | "medium" | "high";
-  message: string;
-}
-```
-
-## Core Functions
-
-### `createMilestone(data)`
-Creates a new milestone linked to requirements.
-
-### `assessHealth(milestone, sprintVelocity)`
-Calculates health score and risk level.
-
-### `checkMilestones(milestones, velocity)`
-Batch assessment of all milestones.
-
-### `alertMilestoneRisk(health)`
-Generates alert text for at-risk milestones.
-
-## Acceptance Criteria
-
-- [ ] Creates and tracks milestones
-- [ ] Calculates completion percentage
-- [ ] Risk assessment based on velocity
-- [ ] Alert messages for at-risk milestones
-- [ ] Unit tests

package/RFC/0076_BACKLOG_MANAGER.md

@@ -1,24 +0,0 @@
-# RFC-0076 — BACKLOG MANAGER
-
-## Purpose
-Defines the architecture contract for the backlog manager subsystem.
-
-## Scope
-- Responsibilities
-- Public interfaces
-- Runtime events
-- Integration points
-- Acceptance criteria
-
-## Key Interfaces
-- Service
-- Configuration
-- Events
-
-## Dependencies
-To be refined during implementation review.
-
-## Acceptance
-- Typed API
-- Deterministic behavior
-- Unit tests

package/RFC/0077_HUMAN_APPROVAL_GATE.md

@@ -1,24 +0,0 @@
-# RFC-0077 — HUMAN APPROVAL GATE
-
-## Purpose
-Defines the architecture contract for the human approval gate subsystem.
-
-## Scope
-- Responsibilities
-- Public interfaces
-- Runtime events
-- Integration points
-- Acceptance criteria
-
-## Key Interfaces
-- Service
-- Configuration
-- Events
-
-## Dependencies
-To be refined during implementation review.
-
-## Acceptance
-- Typed API
-- Deterministic behavior
-- Unit tests

package/RFC/0078_RELEASE_MANAGER.md

@@ -1,24 +0,0 @@
-# RFC-0078 — RELEASE MANAGER
-
-## Purpose
-Defines the architecture contract for the release manager subsystem.
-
-## Scope
-- Responsibilities
-- Public interfaces
-- Runtime events
-- Integration points
-- Acceptance criteria
-
-## Key Interfaces
-- Service
-- Configuration
-- Events
-
-## Dependencies
-To be refined during implementation review.
-
-## Acceptance
-- Typed API
-- Deterministic behavior
-- Unit tests

package/RFC/0079_VERSION_MANAGER.md

@@ -1,24 +0,0 @@
-# RFC-0079 — VERSION MANAGER
-
-## Purpose
-Defines the architecture contract for the version manager subsystem.
-
-## Scope
-- Responsibilities
-- Public interfaces
-- Runtime events
-- Integration points
-- Acceptance criteria
-
-## Key Interfaces
-- Service
-- Configuration
-- Events
-
-## Dependencies
-To be refined during implementation review.
-
-## Acceptance
-- Typed API
-- Deterministic behavior
-- Unit tests

package/RFC/0080_DEPLOYMENT_PIPELINE.md

@@ -1,24 +0,0 @@
-# RFC-0080 — DEPLOYMENT PIPELINE
-
-## Purpose
-Defines the architecture contract for the deployment pipeline subsystem.
-
-## Scope
-- Responsibilities
-- Public interfaces
-- Runtime events
-- Integration points
-- Acceptance criteria
-
-## Key Interfaces
-- Service
-- Configuration
-- Events
-
-## Dependencies
-To be refined during implementation review.
-
-## Acceptance
-- Typed API
-- Deterministic behavior
-- Unit tests

package/RFC/0081_MULTI_USER_RUNTIME.md

@@ -1,24 +0,0 @@
-# RFC-0081 — MULTI USER RUNTIME
-
-## Purpose
-Defines the architecture contract for the multi user runtime subsystem.
-
-## Scope
-- Responsibilities
-- Public interfaces
-- Runtime events
-- Integration points
-- Acceptance criteria
-
-## Key Interfaces
-- Service
-- Configuration
-- Events
-
-## Dependencies
-To be refined during implementation review.
-
-## Acceptance
-- Typed API
-- Deterministic behavior
-- Unit tests

package/RFC/0082_RBAC.md

@@ -1,24 +0,0 @@
-# RFC-0082 — RBAC
-
-## Purpose
-Defines the architecture contract for the rbac subsystem.
-
-## Scope
-- Responsibilities
-- Public interfaces
-- Runtime events
-- Integration points
-- Acceptance criteria
-
-## Key Interfaces
-- Service
-- Configuration
-- Events
-
-## Dependencies
-To be refined during implementation review.
-
-## Acceptance
-- Typed API
-- Deterministic behavior
-- Unit tests