pi-harness-runtime 1.1.166 → 1.1.167

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

@@ -0,0 +1,504 @@
+# 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:
+
+- `/home/frappe/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
+/home/frappe/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": "/home/frappe/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 `/home/frappe/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

@@ -0,0 +1,108 @@
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-harness-runtime",
-  "version": "1.1.166",
+  "version": "1.1.167",
   "description": "[BETA] Codex-style /usage status + autonomous coding harness for pi. Not production ready — expect breaking changes.",
   "type": "module",
   "scripts": {
@@ -27,6 +27,7 @@
   },
   "files": [
     "*.ts",
+    "*.md",
     "harness/**/*.ts",
     "packages/**/src/**/*.{ts,js}",
     "packages/**/dist/**/*.{js,d.ts,js.map,d.ts.map}",
@@ -36,6 +37,7 @@
     ".pi/plugins/**/*",
     "package.json",
     "README.md",
+    "AGENTS.md",
     "CHANGELOG.md",
     "LICENSE",
     "config.toml.example"

package/packages/a2a-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/a2a-adapter",
-  "version": "1.1.166",
+  "version": "1.1.167",
   "type": "module",
   "description": "Google Agent-to-Agent (A2A) protocol adapter for pi-harness",
   "main": "dist/index.js",

package/packages/agent-policy/dist/extension.d.ts

@@ -13,7 +13,8 @@ import type { AgentPolicyConfig } from "./types.js";
  */
 export declare function registerAgentPolicy(pi: ExtensionAPI, config: AgentPolicyConfig): void;
 /**
- * Register with default configuration pointing to harness AGENTS.md.
+ * Register with default configuration pointing to harness rules.
+ * Checks for AGENTS.md first, then RULES.md as fallback.
  */
 export declare function registerDefault(pi: ExtensionAPI): void;
 //# sourceMappingURL=extension.d.ts.map

package/packages/agent-policy/dist/extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAapB;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,iBAAiB,GACxB,IAAI,CA8SN;AA8DD;;GAEG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAYtD"}
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAapB;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,iBAAiB,GACxB,IAAI,CA8SN;AA8DD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAiBtD"}

package/packages/agent-policy/dist/extension.js

@@ -309,14 +309,19 @@ async function checkForBlockingFindings(_ctx, piLensAvailable) {
 // Convenience Export
 // ---------------------------------------------------------------------------
 /**
- * Register with default configuration pointing to harness AGENTS.md.
+ * Register with default configuration pointing to harness rules.
+ * Checks for AGENTS.md first, then RULES.md as fallback.
  */
 export function registerDefault(pi) {
-    // Resolve AGENTS.md relative to the package root (pi-harness-runtime/)
+    // Resolve harness rules relative to the package root (pi-harness-runtime/)
     // import.meta.url is packages/agent-policy/src/extension.ts
     // So we go up 3 levels to reach the package root
     const packageRoot = new URL("../../..", import.meta.url);
-    const harnessRulesPath = new URL("AGENTS.md", packageRoot);
+    const { existsSync } = require("node:fs");
+    // Check for AGENTS.md first, then RULES.md as fallback
+    const agentsPath = new URL("AGENTS.md", packageRoot);
+    const rulesPath = new URL("RULES.md", packageRoot);
+    const harnessRulesPath = existsSync(agentsPath) ? agentsPath : rulesPath;
     registerAgentPolicy(pi, {
         harnessRulesPath,
         requireReceiptBeforeMutation: true,