@avee1234/selfpatch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhi Das
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# selfpatch
+
+[![CI](https://github.com/abhid1234/selfpatch/actions/workflows/ci.yml/badge.svg)](https://github.com/abhid1234/selfpatch/actions/workflows/ci.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)
+
+**[▶ Play with it live](https://selfpatch.vercel.app)** · watch an AI improve itself, try to reward-hack, and get caught — running the real library in your browser.
+**[📖 Read the deep dive](https://abhid.substack.com/p/watching-an-ai-cheat-and-stopping)** · *Watching an AI Cheat — and Stopping It.*
+
+**The trust substrate for self-learning agents.** Every change an agent makes to *itself* — its prompts, skills, weights, or scaffolding — becomes a verifiable, gated, revertible artifact. So a self-improving agent can be trusted, audited, and rolled back. Zero dependencies.
+
+> Working name — see [`vision.md`](vision.md). Grounded in the 2026 state of self-improving agents and Lilian Weng's *Harness Engineering for Self-Improvement*.
+
+## The problem
+
+Self-improvement is shipping at four layers — context/prompt (GEPA, Reflexion), memory/skills (Agent Skills, Voyager), weights (SEAL), and scaffolding (Darwin Gödel Machine). They all share one unsolved problem: **generating a self-improvement is easy now; verifying it is the bottleneck.**
+
+The deepest failure mode is **reward hacking** — give an agent a number to optimize and it games the number, not the task, so its *reported* score runs away from its *true* ability (Goodhart's law, live). It's not a bug you patch; it's the inevitable consequence of optimizing an imperfect objective. selfpatch is the neutral layer underneath every self-improving system that stops a gamed self-edit from shipping unnoticed.
+
+## The idea — a pull request against its own brain
+
+A self-edit shouldn't be a silent mutation — it should be a reviewable artifact. However an agent proposes to change itself, at any layer, that change becomes a **self-patch**, and four verbs decide its fate:
+
+```bash
+selfpatch propose  edit.diff              # capture a self-edit as a self-patch (not applied)
+selfpatch verify   patch.json             # run its held-out check OUTSIDE the loop — regress = block
+selfpatch gate     patch.json -p pol.json # approve | human-gate | block (protected surfaces, blast radius)
+selfpatch apply    patch.json             # apply + append to the hash-chained ledger
+selfpatch revert   <id>                   # roll back any applied patch
+```
+
+## Quickstart
+
+```bash
+npm i @avee1234/selfpatch
+```
+
+```js
+import { proposeSelfPatch, verifySelfPatch, gate } from '@avee1234/selfpatch'
+
+// 1 · capture the self-edit as an artifact — nothing is applied yet
+const patch   = proposeSelfPatch(edit, { layer: 'prompt', rationale })
+
+// 2 · run YOUR held-out check, outside the loop — regress = blocked
+const checked = await verifySelfPatch(patch, { runCheck })
+
+// 3 · policy decides: approve · human-gate · block
+const { decision } = gate(checked, policy)
+```
+
+That's the whole integration surface. Your existing improvement loop keeps generating edits; selfpatch just makes each one earn its place before it lands — and gives you a revert button for the ones that shouldn't have.
+
+## Why it's different
+
+- **The evaluator lives *outside* the loop** by construction — a self-edit that games the reward regresses the held-out check and dies there. The safety property falls out of the architecture, not vigilance.
+- **Protected surfaces** let you declare what a harness may never edit about itself — the evaluator, the safety rules, the permission boundary. The most dangerous self-edit is the one that changes what "good" means; this makes that structurally impossible.
+- **The ledger** is a hash-chained, tamper-evident changelog of how an agent evolved its own mind — approved *and* blocked patches — each revertible by id. Catastrophic forgetting stops being terminal: a regression just rolls back.
+
+Same open-format-and-conformance playbook as [opentrajectory](https://github.com/abhid1234/opentrajectory) and [constraintguard](https://github.com/abhid1234/constraintguard) — but one layer up: it governs *how an agent is allowed to change itself*, across every layer.
+
+## Built by the factory it governs
+
+selfpatch was built almost entirely by an autonomous **agent factory** — a pipeline that triages, specs, implements, reviews, and ships, with a human at two approval gates. That factory's weekly **retro loop edits its own skills** — an ungoverned layer-4 self-modifier, and selfpatch's first real user. The tool that keeps agents honest was built by agents, and now keeps them honest too.
+
+Status: **implementation kicked off** — see [`roadmap.md`](roadmap.md). Live prototype + field map in [`site/`](site/). MIT · zero dependencies · harness-neutral.