pi-harness-runtime 0.10.13 → 0.10.15

package/RFC/0041_PROMPT_COMPILER.md

@@ -1,232 +0,0 @@
-# RFC-0041 — Prompt Compiler
-
-Status: Draft  
-Target package: `packages/prompt-compiler`  
-Owner: Runtime Intelligence  
-Depends on: RFC-0042 Context Compiler, RFC-0043 Requirement Compiler
-
-## 1. Problem
-
-Provider prompts are currently assembled informally. That creates inconsistent instructions, duplicate context, missing output contracts, and poor resumability. The Prompt Compiler shall convert normalized runtime inputs into a deterministic `PromptPackage` that can be sent to Codex, MiniMax, GLM, or another provider adapter.
-
-The compiler does not call a model. It produces an immutable artifact that can be inspected, hashed, cached, resumed, and replayed.
-
-## 2. Inputs and outputs
-
-Inputs:
-
-```ts
-export interface PromptCompileRequest {
-  task: CompiledTask;
-  requirement: CompiledRequirement;
-  context: CompiledContext;
-  provider: ProviderTarget;
-  attempt: number;
-  continuation?: ContinuationContext;
-}
-```
-
-Output:
-
-```ts
-export interface PromptPackage {
-  version: "1";
-  taskId: string;
-  provider: ProviderTarget;
-  system: string;
-  user: string;
-  sections: PromptSection[];
-  estimatedInputTokens: number;
-  sourceRefs: SourceReference[];
-  hash: string;
-  createdAt: string;
-}
-```
-
-The generated package is persisted under:
-
-```text
-~/.pi/harness/jobs/<job-id>/prompts/<task-id>/<attempt>/
-+-- prompt.md
-+-- prompt.json
-+-- sources.json
-+-- metadata.json
-```
-
-## 3. Compilation pipeline
-
-```text
-PromptCompileRequest
-  -> normalize input
-  -> select provider profile
-  -> assemble ordered sections
-  -> remove duplicate context
-  -> enforce policy constraints
-  -> estimate token size
-  -> compact optional sections
-  -> validate output contract
-  -> calculate content hash
-  -> persist PromptPackage
-```
-
-Section order is deterministic:
-
-1. Runtime identity
-2. Project rules
-3. Objective
-4. Acceptance criteria
-5. Relevant context
-6. Known constraints
-7. Files in scope
-8. Required output
-9. Tool permissions
-10. Continuation instructions
-
-## 4. Provider profiles
-
-```ts
-export interface ProviderPromptProfile {
-  id: string;
-  supportsSystemPrompt: boolean;
-  preferredInstructionStyle: "xml" | "markdown" | "plain";
-  maximumInputTokens: number;
-  reservedOutputTokens: number;
-  continuationMarker: string;
-}
-```
-
-Provider-specific formatting is allowed only in the final formatting stage. Core prompt semantics must remain provider-independent.
-
-## 5. Deduplication
-
-Context entries are normalized using:
-
-```ts
-normalize(text) =
-  lowercase(
-    collapseWhitespace(
-      stripMarkdownDecoration(text)
-    )
-  )
-```
-
-Exact duplicate normalized entries are removed. Near-duplicate removal may use a configurable similarity threshold but must be disabled by default because accidental semantic deletion is more dangerous than moderate token waste.
-
-## 6. Token budget
-
-The compiler must reject a package when required sections exceed:
-
-```text
-provider.maximumInputTokens - provider.reservedOutputTokens
-```
-
-Optional context sections are compacted in this order:
-
-1. Historical logs
-2. Previous successful examples
-3. Low-priority repository notes
-4. Non-blocking discussion
-5. Redundant file summaries
-
-Project rules, security constraints, objective, and acceptance criteria are never automatically removed.
-
-## 7. Validation
-
-Compilation fails when:
-
-- `task.id` is empty.
-- Objective is empty.
-- No expected output is defined.
-- A referenced source cannot be resolved and is marked required.
-- Token budget remains exceeded after optional compaction.
-- The prompt grants a tool permission forbidden by the Policy Engine.
-
-```ts
-export type PromptCompileErrorCode =
-  | "INVALID_TASK"
-  | "MISSING_OBJECTIVE"
-  | "MISSING_OUTPUT_CONTRACT"
-  | "UNRESOLVED_REQUIRED_SOURCE"
-  | "TOKEN_BUDGET_EXCEEDED"
-  | "POLICY_CONFLICT";
-```
-
-## 8. Runtime events
-
-```ts
-type PromptCompilerEvent =
-  | { type: "prompt.compilation.started"; taskId: string; attempt: number }
-  | { type: "prompt.compaction.applied"; taskId: string; removed: string[] }
-  | { type: "prompt.compilation.completed"; taskId: string; hash: string }
-  | { type: "prompt.compilation.failed"; taskId: string; code: PromptCompileErrorCode };
-```
-
-## 9. Continuation support
-
-When a provider stops because of output limits, the Partial Response Recovery subsystem supplies:
-
-```ts
-export interface ContinuationContext {
-  previousResponsePath: string;
-  completedItems: string[];
-  incompleteItems: string[];
-  instruction: "continue_without_repeating";
-}
-```
-
-The compiler must include the previous response reference and incomplete work list, while explicitly forbidding repetition of completed sections.
-
-## 10. Security
-
-The compiler must never embed:
-
-- Provider API keys
-- Browser cookies
-- OAuth tokens
-- Unredacted secrets from environment files
-- Entire `.git` history
-- Files excluded by project policy
-
-All source material passes through a redaction interface before assembly.
-
-## 11. Reference algorithm
-
-```ts
-export async function compilePrompt(
-  request: PromptCompileRequest,
-  deps: PromptCompilerDependencies,
-): Promise<PromptPackage> {
-  const normalized = normalizeRequest(request);
-  const profile = deps.profiles.get(normalized.provider);
-  const rawSections = await deps.sectionBuilder.build(normalized);
-  const redacted = await deps.redactor.redact(rawSections);
-  const deduplicated = deduplicateSections(redacted);
-  const budgeted = compactToBudget(deduplicated, profile);
-  validateSections(budgeted, normalized, profile);
-  const rendered = renderForProvider(budgeted, profile);
-  const hash = deps.hasher.sha256(rendered.system + "\n" + rendered.user);
-
-  return {
-    version: "1",
-    taskId: normalized.task.id,
-    provider: normalized.provider,
-    system: rendered.system,
-    user: rendered.user,
-    sections: budgeted,
-    estimatedInputTokens: deps.tokenEstimator.estimate(rendered),
-    sourceRefs: collectSourceRefs(budgeted),
-    hash,
-    createdAt: deps.clock.now().toISOString(),
-  };
-}
-```
-
-## 12. Acceptance criteria
-
-- Identical inputs produce identical prompt content and hash.
-- Required sections are never removed by compaction.
-- Provider formatting does not alter task semantics.
-- Secrets are redacted before persistence.
-- Invalid output contracts fail compilation.
-- Continuation prompts do not repeat completed work.
-- Unit tests cover all error codes.

package/RFC/0042_CONTEXT_COMPILER.md

@@ -1,216 +0,0 @@
-# RFC-0042 — Context Compiler
-
-Status: Draft  
-Target package: `packages/context-compiler`  
-Depends on: Shared Blackboard, OKF Knowledge Bundle, Repository Reader
-
-## 1. Problem
-
-Agents frequently receive either too much repository context or too little. Raw chat history is unstable, repository-wide dumps exceed model limits, and manually selected files make autonomous execution dependent on a human message relay.
-
-The Context Compiler creates a bounded, traceable `CompiledContext` for a specific task.
-
-## 2. Context sources
-
-The compiler may read:
-
-- Shared Blackboard current state
-- Task dependencies and prior agent reports
-- Project rules
-- OKF concepts
-- Repository files
-- Git diff and status
-- Test failures
-- Previous partial responses
-- Framework plugin recommendations
-
-It must not treat all sources equally. Every context item includes priority, freshness, trust, and scope.
-
-```ts
-export interface ContextCandidate {
-  id: string;
-  kind:
-    | "project_rule"
-    | "okf_concept"
-    | "source_file"
-    | "git_diff"
-    | "test_failure"
-    | "agent_report"
-    | "blackboard_state";
-  content: string;
-  source: string;
-  priority: 0 | 1 | 2 | 3;
-  required: boolean;
-  updatedAt?: string;
-  trust: "authoritative" | "generated" | "unverified";
-}
-```
-
-## 3. Output
-
-```ts
-export interface CompiledContext {
-  taskId: string;
-  items: CompiledContextItem[];
-  omitted: OmittedContextItem[];
-  estimatedTokens: number;
-  sourceGraph: ContextSourceEdge[];
-  generatedAt: string;
-}
-```
-
-Every omission must be recorded with a reason such as `duplicate`, `out_of_scope`, `stale`, `budget`, or `policy_denied`.
-
-## 4. Selection algorithm
-
-```text
-collect candidates
- -> apply policy filters
- -> mark required items
- -> score optional items
- -> resolve direct dependencies
- -> deduplicate
- -> fit within context budget
- -> generate source graph
- -> persist compiled context
-```
-
-Suggested score:
-
-```text
-score =
-  priority_weight
-  + direct_file_reference
-  + recent_failure_relevance
-  + dependency_relevance
-  + framework_relevance
-  - stale_penalty
-  - duplication_penalty
-```
-
-The scoring formula is configurable, but required items bypass scoring.
-
-## 5. Progressive disclosure
-
-The compiler should prefer summaries first and source files second:
-
-```text
-OKF concept summary
- -> relevant symbol summary
- -> selected source excerpt
- -> complete source file only when required
-```
-
-Agents may request expansion through a runtime tool, but initial compilation should avoid sending unrelated files.
-
-## 6. Repository slicing
-
-For source code, context is selected by symbol when supported.
-
-```ts
-export interface SourceSlice {
-  file: string;
-  startLine: number;
-  endLine: number;
-  symbols: string[];
-  reason: string;
-  contentHash: string;
-}
-```
-
-A Framework Plugin may provide AST-aware slicing. The generic fallback uses line ranges and import/reference search.
-
-## 7. OKF integration
-
-OKF documents are authoritative for durable architecture and project knowledge only when their frontmatter identifies them as authoritative or approved.
-
-Example:
-
-```yaml
----
-type: Runtime Concept
-title: Shared Blackboard
-authority: approved
-tags: [runtime, coordination]
-timestamp: 2026-07-10T00:00:00+07:00
----
-```
-
-Generated or stale concepts remain usable but receive a lower trust score.
-
-## 8. Freshness and invalidation
-
-Compiled context is invalidated when:
-
-- A selected source file hash changes.
-- A project rule changes.
-- A required OKF concept changes.
-- The task objective changes.
-- A new test failure supersedes an old one.
-- The current Git worktree changes branch or HEAD.
-
-The context cache key contains all selected source hashes.
-
-## 9. Safety boundaries
-
-The Context Compiler must obey include/exclude policies such as:
-
-```yaml
-context:
-  deny:
-    - "**/.env"
-    - "**/*.pem"
-    - "**/credentials/**"
-  allow_large_files: false
-  max_file_bytes: 200000
-```
-
-Denied content is never copied into compiled artifacts. The omission record may contain the file path but not its secret contents.
-
-## 10. Reference interface
-
-```ts
-export interface ContextCompiler {
-  compile(request: ContextCompileRequest): Promise<CompiledContext>;
-  invalidate(reason: ContextInvalidation): Promise<void>;
-}
-
-export interface ContextCompileRequest {
-  jobId: string;
-  task: CompiledTask;
-  maximumTokens: number;
-  worktreePath: string;
-  provider: ProviderTarget;
-}
-```
-
-## 11. Failure handling
-
-- Missing optional source: omit and record.
-- Missing required source: fail.
-- Repository parsing failure: fall back to line-based extraction.
-- Token estimate unavailable: use conservative character estimate.
-- Broken OKF link: preserve concept and record broken edge.
-- Blackboard unavailable: fail because current runtime state is required.
-
-## 12. Tests
-
-Required tests include:
-
-1. Required project rules are always included.
-2. `.env` content is denied.
-3. Duplicate source slices are merged.
-4. Changed file hash invalidates cache.
-5. Broken optional OKF link does not fail compilation.
-6. Broken required source does fail.
-7. Context remains under requested token budget.
-8. Omitted items include explicit reasons.
-
-## 13. Acceptance criteria
-
-- Every compiled item has a source reference.
-- Every omitted candidate has a reason.
-- Required content is never silently dropped.
-- Compiled context is deterministic for identical repository state.
-- Secret-deny patterns are enforced before persistence.
-- OKF concepts and source files can coexist in one source graph.

package/RFC/0043_REQUIREMENT_COMPILER.md

@@ -1,211 +0,0 @@
-# RFC-0043 — Requirement Compiler
-
-Status: Draft  
-Target package: `packages/requirement-compiler`  
-Input owner: Human-on-the-loop TUI
-
-## 1. Problem
-
-Client requirements commonly arrive as prose, mixed Thai/English notes, screenshots, and informal acceptance expectations. Coding agents cannot safely execute ambiguous prose directly.
-
-The Requirement Compiler converts raw requirement input into a validated `CompiledRequirement`. It must preserve uncertainty rather than inventing missing business rules.
-
-## 2. Input
-
-```ts
-export interface RawRequirement {
-  id: string;
-  title?: string;
-  text: string;
-  attachments?: AttachmentReference[];
-  source: "tui" | "file" | "api";
-  submittedBy: string;
-  submittedAt: string;
-}
-```
-
-## 3. Output
-
-```ts
-export interface CompiledRequirement {
-  id: string;
-  title: string;
-  problemStatement: string;
-  goals: RequirementGoal[];
-  nonGoals: string[];
-  constraints: RequirementConstraint[];
-  actors: RequirementActor[];
-  workflows: RequirementWorkflow[];
-  acceptanceCriteria: AcceptanceCriterion[];
-  assumptions: RequirementAssumption[];
-  ambiguities: RequirementAmbiguity[];
-  terminology: Record<string, string>;
-  sourceRefs: SourceReference[];
-  status: "ready" | "needs_human" | "rejected";
-}
-```
-
-## 4. Compilation rules
-
-The compiler separates statements into:
-
-- Explicit facts
-- Explicit requested behavior
-- Constraints
-- Assumptions
-- Ambiguities
-- Suggested implementation details
-
-Suggested implementation details are not converted into mandatory requirements unless the user explicitly marks them as constraints.
-
-Example:
-
-```text
-"We prefer Rust WASM for cropping."
-```
-
-This becomes:
-
-```json
-{
-  "kind": "technology_preference",
-  "value": "Rust WASM",
-  "mandatory": false
-}
-```
-
-## 5. Ambiguity policy
-
-The compiler must not guess values that materially affect behavior, cost, compliance, or data integrity.
-
-```ts
-export interface RequirementAmbiguity {
-  id: string;
-  question: string;
-  blocking: boolean;
-  affectedGoals: string[];
-  evidence: SourceReference[];
-}
-```
-
-When the developer instruction allows best-effort progression, a blocking ambiguity may be converted into an explicit reversible assumption, but the assumption must be visible in output.
-
-## 6. Acceptance criteria normalization
-
-Each criterion should use observable language.
-
-Poor:
-
-```text
-The page should work well.
-```
-
-Compiled:
-
-```json
-{
-  "id": "AC-001",
-  "given": "A valid authenticated user",
-  "when": "The user saves the form",
-  "then": [
-    "The API returns HTTP 200",
-    "The saved record is visible after reload",
-    "No duplicate record is created"
-  ],
-  "automatable": true
-}
-```
-
-## 7. Compliance and risk tags
-
-The compiler identifies requirement areas requiring additional review:
-
-```ts
-type RequirementRisk =
-  | "financial"
-  | "privacy"
-  | "authentication"
-  | "authorization"
-  | "data_migration"
-  | "regulatory"
-  | "destructive_operation";
-```
-
-Risk tags do not replace legal or domain review. They instruct the Master Planner to insert appropriate review tasks.
-
-## 8. Multilingual handling
-
-The original wording must be preserved in source references. The normalized requirement may use the configured project language. Domain terms should be added to `terminology`.
-
-For Thai business systems, the compiler should preserve Thai legal/accounting terms when an English translation could change meaning.
-
-## 9. State model
-
-```text
-received
- -> parsing
- -> normalized
- -> validation
- -> ready
-      or
- -> needs_human
-      or
- -> rejected
-```
-
-Rejected means the requirement is empty, internally impossible, or violates project policy. It does not mean implementation failure.
-
-## 10. Reference function
-
-```ts
-export async function compileRequirement(
-  raw: RawRequirement,
-  deps: RequirementCompilerDependencies,
-): Promise<CompiledRequirement> {
-  const extracted = await deps.extractor.extract(raw);
-  const classified = classifyStatements(extracted);
-  const normalized = normalizeRequirement(classified, raw);
-  const ambiguities = detectAmbiguities(normalized);
-  const acceptanceCriteria = normalizeAcceptance(normalized);
-  const risks = detectRisks(normalized);
-
-  return validateCompiledRequirement({
-    ...normalized,
-    acceptanceCriteria,
-    ambiguities,
-    risks,
-    status: ambiguities.some(item => item.blocking)
-      ? "needs_human"
-      : "ready",
-  });
-}
-```
-
-## 11. Failure cases
-
-- Empty input: reject.
-- Unsupported attachment: retain reference and mark extraction failure.
-- Contradictory requirements: create blocking ambiguity.
-- Missing actor: infer only when obvious; otherwise ambiguity.
-- Non-testable acceptance statement: retain as manual criterion.
-- Requirement asks for forbidden operation: reject with policy code.
-
-## 12. Tests
-
-1. Explicit requirement remains explicit.
-2. Preference is not promoted to mandatory constraint.
-3. Contradictory statements create ambiguity.
-4. Acceptance criteria become Given/When/Then.
-5. Thai terminology remains in the glossary.
-6. Financial requirement receives risk tag.
-7. Empty requirement is rejected.
-8. Source references remain traceable.
-
-## 13. Acceptance criteria
-
-- No material requirement is invented.
-- Every compiled goal traces to source text.
-- Ambiguities are explicit.
-- Acceptance criteria are observable.
-- Risk tags are emitted for planner use.
-- Original user language is preserved in source references.