pi-harness-runtime 1.1.445 → 1.1.446

package/harness/skills-plan/2026-07-12-public-skill-export-and-sync-design.md

@@ -1,504 +0,0 @@
-# Public Skill Export and Sync Design for `pi-harness-runtime`
-
-## Purpose
-
-This document turns the high-level Herdr adaptation plan into a concrete design for:
-
-1. exporting selected MooCoding skills into `pi-harness-runtime`
-2. sanitizing them before publication
-3. adding a **sync** function because the live skill source is continuously updated
-
-This design assumes the live private skill corpus remains here:
-
-- `~/frappe-bench/.claude-plugins/moocoding-skills/skills/*`
-
-That location remains the editable operational knowledge base.
-
----
-
-## Design Principles
-
-### 1. Private source stays private
-
-The bench-side MooCoding skills directory is the authoring source of truth.
-
-It is never treated as:
-
-- a publishable package directory
-- a public docs source
-- a direct npm skill distribution source
-
-### 2. Sync is not publish
-
-Because the source corpus changes often, we need sync.
-
-But **sync must only move content into a private staging area**, never into public package assets automatically.
-
-### 3. Export is gated
-
-Nothing enters `pi-harness-runtime/skills/*` until it passes:
-
-- sanitization checks
-- explicit approval
-- manifest tracking
-
-### 4. Public package content must be reproducible
-
-Every public skill should have traceable provenance:
-
-- source skill path
-- source fingerprint/hash
-- sanitized export timestamp
-- approval record
-
----
-
-## Proposed Directory Layout
-
-## A. Private live source
-
-Outside repo package boundary:
-
-```text
-~/frappe-bench/.claude-plugins/moocoding-skills/skills/
-  <skill-name>/
-    SKILL.md
-```
-
-## B. Private repo-local staging area
-
-Inside `pi-harness-runtime`, but excluded from publishable package contents:
-
-```text
-harness/skills-staging/
-  source-mirror/
-    <skill-name>/
-      SKILL.md
-  sanitized-candidates/
-    <skill-name>/
-      SKILL.md
-  reports/
-    sync-report.json
-    sanitize-report.json
-    approval-report.json
-  manifests/
-    source-index.json
-    approval-index.json
-```
-
-Notes:
-
-- `source-mirror/` is a synced private mirror of selected private skills
-- `sanitized-candidates/` contains transformed or reviewed versions
-- nothing under `harness/skills-staging/` should be treated as publishable skill content by package manifests
-
-## C. Public distributable area
-
-Already exposed by package manifest:
-
-```text
-skills/
-  <public-skill-name>/
-    SKILL.md
-```
-
-Only approved sanitized skills may appear here.
-
----
-
-## Lifecycle Model
-
-Each skill moves through explicit states.
-
-```text
-private-source
-  -> synced-private-mirror
-  -> sanitize-check
-  -> sanitized-candidate
-  -> approved
-  -> exported-public
-```
-
-### State meanings
-
-- `private-source`: original bench-side skill
-- `synced-private-mirror`: latest mirrored copy inside repo staging
-- `sanitize-check`: automated/manual review in progress
-- `sanitized-candidate`: safe draft pending approval
-- `approved`: explicitly allowed for public export
-- `exported-public`: copied into `skills/*`
-
----
-
-## The Required Sync Function
-
-Because the private source keeps changing, add a **one-way sync** command.
-
-## Sync command responsibility
-
-The sync function should:
-
-1. read selected skills from the private source tree
-2. copy them into `harness/skills-staging/source-mirror/`
-3. compute fingerprints/hashes
-4. record changes since last sync
-5. never touch `skills/*`
-6. never imply approval
-
-## Command shape
-
-Suggested command surface:
-
-```bash
-bun scripts/skills-sync.ts --skill bench-commands
-bun scripts/skills-sync.ts --all-from-manifest
-bun scripts/skills-sync.ts --changed-only
-bun scripts/skills-sync.ts --check-only
-```
-
-## Sync modes
-
-### Mode 1 — targeted sync
-
-For one skill:
-
-```bash
-bun scripts/skills-sync.ts --skill form-state-persistence-fix
-```
-
-Use when preparing a specific skill for review.
-
-### Mode 2 — manifest-driven sync
-
-```bash
-bun scripts/skills-sync.ts --all-from-manifest
-```
-
-Reads a maintained allowlist of candidate private skills and refreshes their staging mirrors.
-
-### Mode 3 — changed-only sync
-
-```bash
-bun scripts/skills-sync.ts --changed-only
-```
-
-Only updates staged mirror copies when the source fingerprint differs.
-
-### Mode 4 — check-only sync
-
-```bash
-bun scripts/skills-sync.ts --check-only
-```
-
-Reports drift without copying files.
-
----
-
-## Sync Manifest Design
-
-Introduce a manifest that defines which private skills are even eligible for staging sync.
-
-Example:
-
-```json
-{
-  "sourceRoot": "~/frappe-bench/.claude-plugins/moocoding-skills/skills",
-  "skills": [
-    {
-      "sourceName": "bench-commands",
-      "targetName": "bench-commands",
-      "sync": true,
-      "publicCandidate": false
-    },
-    {
-      "sourceName": "form-state-persistence-fix",
-      "targetName": "form-state-persistence-fix",
-      "sync": true,
-      "publicCandidate": true
-    }
-  ]
-}
-```
-
-Suggested file:
-
-```text
-harness/skills-staging/manifests/source-index.json
-```
-
-## Why this matters
-
-- prevents accidental sync of the entire private corpus
-- makes sync selection explicit
-- creates a reviewable inventory
-
----
-
-## Sanitization Design
-
-## Sanitization command responsibility
-
-The sanitization step should take a mirrored private skill and produce a candidate public version.
-
-Suggested command:
-
-```bash
-bun scripts/skills-sanitize.ts --skill form-state-persistence-fix
-bun scripts/skills-sanitize.ts --all-approved-candidates
-bun scripts/skills-sanitize.ts --check-only
-```
-
-## Sanitization checks
-
-Automated checks should flag:
-
-- client names
-- internal company names when not intended for disclosure
-- private domains and internal URLs
-- IP addresses
-- credentials, tokens, cookies, bearer strings
-- SSH host aliases
-- private repo URLs
-- machine-specific absolute paths when not acceptable for public docs
-- support references that reveal private operations
-
-## Sanitization outputs
-
-For each skill, produce:
-
-- candidate sanitized `SKILL.md`
-- machine-readable report
-- human-readable warnings
-
-Suggested report path:
-
-```text
-harness/skills-staging/reports/sanitize-report.json
-```
-
-## Sanitization result classes
-
-- `pass`: no blocking issues found
-- `warn`: manual review required
-- `fail`: cannot proceed without edits
-
----
-
-## Approval Design
-
-A sanitized candidate still should not publish automatically.
-
-Add an approval manifest, for example:
-
-```json
-{
-  "skills": [
-    {
-      "targetName": "form-state-persistence-fix",
-      "approved": true,
-      "approvedBy": "manual",
-      "sourceHash": "abc123",
-      "sanitizedHash": "def456",
-      "approvedAt": "2026-07-12T00:00:00Z"
-    }
-  ]
-}
-```
-
-Suggested file:
-
-```text
-harness/skills-staging/manifests/approval-index.json
-```
-
-Approval rules:
-
-- only `approved: true` entries may export to `skills/*`
-- approval must bind to a specific sanitized hash
-- if the private source changes later, the sync hash changes and approval becomes stale
-
----
-
-## Export Design
-
-## Export command responsibility
-
-The export command copies only approved sanitized candidates into the public package skill directory.
-
-Suggested command:
-
-```bash
-bun scripts/skills-export.ts --skill form-state-persistence-fix
-bun scripts/skills-export.ts --all-approved
-bun scripts/skills-export.ts --check-only
-```
-
-## Export rules
-
-- source must exist in `sanitized-candidates/`
-- approval record must exist and match current sanitized hash
-- export target must be inside `skills/<targetName>/SKILL.md`
-- export must not read directly from the private source tree
-
-## Export outputs
-
-- created or updated `skills/<targetName>/SKILL.md`
-- export report with source and hash provenance
-
----
-
-## Recommended Command Pipeline
-
-For a single skill:
-
-```bash
-# 1. refresh private staging copy from live source
-bun scripts/skills-sync.ts --skill form-state-persistence-fix
-
-# 2. sanitize into candidate public version
-bun scripts/skills-sanitize.ts --skill form-state-persistence-fix
-
-# 3. review and mark approved in approval manifest
-# (manual step or dedicated approval command)
-
-# 4. export only approved sanitized candidate
-bun scripts/skills-export.ts --skill form-state-persistence-fix
-```
-
----
-
-## Drift and Re-Sync Behavior
-
-Because the source skills keep changing, we need clear drift handling.
-
-## Drift rule
-
-If private source hash changes after approval:
-
-- existing public export remains as-is
-- approval becomes stale for the next export cycle
-- sync report must show the skill as changed
-- sanitization and approval must run again before re-export
-
-## Why this is important
-
-This avoids two bad outcomes:
-
-1. silently publishing new private content
-2. breaking provenance between approved content and exported content
-
----
-
-## Suggested Provenance Fields
-
-Each staged and exported skill record should track:
-
-- `sourceName`
-- `sourcePath`
-- `targetName`
-- `sourceHash`
-- `mirrorHash`
-- `sanitizedHash`
-- `lastSyncedAt`
-- `lastSanitizedAt`
-- `lastApprovedAt`
-- `lastExportedAt`
-- `status`
-
-This can live in JSON manifests or per-skill metadata files.
-
----
-
-## Interaction with `packages/skill-registry`
-
-This design keeps publication and runtime discovery separate.
-
-### Short term
-
-No registry changes are required to begin:
-
-- `skills/*` remains the public packaged skill surface
-- staging stays private under `harness/skills-staging/*`
-
-### Later optional enhancement
-
-`packages/skill-registry` may support reading:
-
-- bundled public skills from `skills/*`
-- local private staged or source skills from configured paths
-
-But that future loader must preserve source classification:
-
-- `public-bundled`
-- `private-staged`
-- `private-external`
-
-And must never auto-publish private sources.
-
----
-
-## Minimal First Implementation
-
-To keep scope controlled, implement in this order:
-
-### Step 1
-
-Add manifests and directory structure:
-
-- `harness/skills-staging/manifests/source-index.json`
-- `harness/skills-staging/manifests/approval-index.json`
-
-### Step 2
-
-Implement `skills-sync.ts`
-
-- explicit allowlist only
-- no package exports touched
-
-### Step 3
-
-Implement `skills-sanitize.ts`
-
-- reports + candidate output
-- fail/warn/pass results
-
-### Step 4
-
-Implement `skills-export.ts`
-
-- approved candidates only
-- writes to `skills/*`
-
-### Step 5
-
-Document operator workflow
-
-- sync
-- sanitize
-- approve
-- export
-
----
-
-## Non-Goals
-
-This design does **not** recommend:
-
-- syncing the whole private corpus into public package directories
-- publishing directly from `~/frappe-bench/.claude-plugins/moocoding-skills/skills/*`
-- replacing the live MooCoding source with `pi-harness-runtime/skills/*`
-- auto-approving sanitized output without human review
-
----
-
-## Recommendation
-
-Add the **sync** function, but make it explicitly:
-
-- one-way
-- allowlist-driven
-- private-staging-only
-- provenance-aware
-- separate from export
-
-That gives you freshness from the always-changing MooCoding corpus without sacrificing privacy or accidentally turning the package into a mirror of unsanitized internal knowledge.

package/harness/skills-plan/ACTION-PLAN.md

@@ -1,108 +0,0 @@
-# Multi-Day Action Plan: 100 RFCs to Production
-
-Based on review of all 100 RFCs (0001–0100) and IMPLEMENTATION/* entries.
-
----
-
-## ✅ Day 1 — Already Done
-
-- **RFC-0052 Skill Registry** — capability registry integration, `invokeBestMatch`, capability checking, extended defaults, 13 new tests (31/31 passing)
-- **RFC-0060 Memory Engine** — `validateConcept`, `writeConcept`, `search`, `promoteFromBlackboard`, `extractLinks`, `exportToOkf` (18/18 passing)
-- **40 new RFCs** (0061–0100) committed with stub IMPLEMENTATION directories
-
----
-
-## 📋 Remaining Work (by priority)
-
-### 🔴 High Priority — Foundation Dependencies
-
-These packages block multiple others. Must implement first.
-
-| Package | RFC | Blocks | Key Tasks |
-|---------|-----|--------|-----------|
-| `framework-detector` | 0038 | 0040, 0061–0066 | Auto-detect project framework from files, env, deps |
-| `framework-plugin-sdk` | 0040 | 0061–0066 | SDK for writing framework plugins, manifest schema, plugin API |
-| `model-registry` | 0053 | 0054, cost-optimizer | `models.list()` pagination, alias vs snapshot, price table |
-| `capability-registry` | 0051 | 0052 (done), 0091–0096 | Capability definitions, provider support matrix |
-
-### 🟡 Medium Priority — Core Systems
-
-Implement these in parallel after foundation.
-
-| Package | RFC | Key Tasks |
-|---------|-----|-----------|
-| `code-generation` | 0037 | Scaffold generation, template engine, multi-framework support |
-| `code-review` | 0036 | AST analysis, rule engine, lint integration, multi-LLM review |
-| `evaluation-engine` | 0057 | Test runner, pass/fail criteria, benchmark suite |
-| `learning-engine` | 0058 | Pattern extraction, weight updates, learning from outcomes |
-| `experience-replay` | 0059 | Experience storage, retrieval, replay for similar tasks |
-| `performance-optimizer` | 0056 | Token estimation, context window management, cache |
-| `task-compiler` | 0044 | Task graph executor, dependency resolution, parallel execution |
-
-### 🟢 Lower Priority — Autonomous Features (RFC 0091–0100)
-
-These depend on core systems above. Implement after core is stable.
-
-| Package | RFC | Description |
-|---------|-----|-------------|
-| `autonomous-architecture-review` | 0091 | AI reviews PRs against architecture rules |
-| `autonomous-refactoring` | 0092 | Auto-suggest/apply refactors |
-| `autonomous-bug-fixing` | 0093 | Auto-fix from bug reports + test failures |
-| `autonomous-performance-tuning` | 0094 | Profile + suggest optimizations |
-| `autonomous-security-review` | 0095 | Scan for security issues |
-| `autonomous-cost-optimization` | 0096 | Suggest/reduce API costs |
-| `autonomous-documentation` | 0097 | Auto-generate/update docs |
-| `autonomous-knowledge-management` | 0098 | Maintain knowledge graph |
-| `runtime-evolution-engine` | 0099 | Self-improve from outcomes |
-| `self-developing-runtime` | 0100 | Closed loop: build -> test -> learn -> improve |
-
----
-
-## 📅 Suggested Day Breakdown
-
-### Day 2: Framework Foundation
-1. `framework-detector` — detect Frappe, Next.js, React/Vite, Django, Laravel
-2. `framework-plugin-sdk` — plugin manifest schema, lifecycle hooks, TypeScript SDK
-3. Verify: `npm run build` passes, tests green
-
-### Day 3: Model + Capability Foundation
-1. `capability-registry` — capability definitions, provider matrix
-2. `model-registry` — paginated `models.list()`, alias/snapshot separation, pricing
-3. `cost-optimizer` — spend tracking, routing by cost/speed/length
-
-### Day 4: Code Intelligence
-1. `code-generation` — scaffold templates, multi-framework support
-2. `code-review` — AST parsing, rule engine, GitHub integration
-3. `evaluation-engine` — benchmark harness, pass/fail criteria
-
-### Day 5–7: Learning + Experience
-1. `learning-engine` — pattern extraction, weight updates
-2. `experience-replay` — storage, similarity search, retrieval
-3. `task-compiler` — parallel task execution, dependency graph
-
-### Day 8+: Autonomous Features
-- Implement RFC 0091–0100 one by one, each with tests + integration
-- Start with 0091 (architecture review) as it's most immediately useful
-
----
-
-## !️ Key Conventions
-
-- All packages: `src/` + `test/` + `dist/`, TypeScript, `bun test`
-- Export types from `src/index.ts`
-- Build before commit: `bun run build && bun test`
-- Dist files (generated): commit after build
-- RFC stubs (0061–0100): add actual AI brief content before implementing
-
----
-
-## 📁 IMPLEMENTATION Structure Per RFC
-
-Each IMPLEMENTATION/*/ has 5 files:
-- **TASKS.md** — numbered implementation checklist
-- **ACCEPTANCE_CRITERIA.md** — done conditions
-- **FILES.md** — expected source file layout
-- **AI_BRIEF.md** — detailed AI instruction for implementation
-- **TESTS.md** — test scenarios
-
-Fill in AI_BRIEF.md before starting implementation.

package/packages/a2a-adapter/README.md

@@ -1,35 +0,0 @@
-# @pi/a2a-adapter
-
-Google Agent-to-Agent (A2A) protocol adapter for pi-harness.
-
-## Protocol
-
-Implements [Google A2A Protocol v1.0](https://google.github.io/A2A/).
-
-## Usage
-
-### Expose as A2A Agent
-
-```typescript
-import { createAgentCard, routeTask, getTask } from "@pi/a2a-adapter";
-
-const card = createAgentCard({
-  name: "pi-harness",
-  description: "AI coding harness",
-  url: "http://localhost:3000",
-  version: "0.9.4",
-});
-// Serve card at /.well-known/agent.json
-
-const task = await routeTask({ role: "user", content: "Analyze code" });
-```
-
-### Delegate to Remote Agent
-
-```typescript
-import { A2AClient } from "@pi/a2a-adapter";
-
-const client = new A2AClient("http://remote-agent:3000");
-const agentCard = await client.discoverAgent();
-const handle = await client.sendTask("Analyze my codebase");
-```

package/packages/a2a-adapter/dist/agent.d.ts

@@ -1,27 +0,0 @@
-/**
- * A2A Adapter — A2A Agent (RFC-0069)
- *
- * Expose this harness agent as an A2A-compatible agent.
- */
-import type { AgentCard, A2AAgentConfig, Task, TaskMessage } from "./types.js";
-/**
- * Create an AgentCard for this harness agent
- */
-export declare function createAgentCard(config: A2AAgentConfig): AgentCard;
-/**
- * Route incoming A2A task to harness skill-registry
- */
-export declare function routeTask(message: TaskMessage): Promise<Task>;
-/**
- * Get task by ID
- */
-export declare function getTask(taskId: string): Task | null;
-/**
- * Cancel a task
- */
-export declare function cancelTask(taskId: string): boolean;
-/**
- * Generate task status update SSE
- */
-export declare function taskStatusUpdateSSE(taskId: string): string;
-//# sourceMappingURL=agent.d.ts.map

package/packages/a2a-adapter/dist/agent.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACX,SAAS,EACT,cAAc,EACd,IAAI,EACJ,WAAW,EAGX,MAAM,YAAY,CAAC;AAUpB;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,CAiCjE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BnE;AASD;;GAEG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEnD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAMlD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAgB1D"}