docs(rsi): Loop C adoption contract and credits

Writes down the rules any future harness-optimization work must meet:
live tasks propose and benchmarks adopt, owner approval per adoption,
immutable gates and scope checks, one-step rollback through prompt
versions, flag off by default, bounded edits, and paired attribution.

Credits harness2 (Google Research, Apache-2.0, arXiv 2610.14224) for the
Library admission rule and propose/probe/compose shape, awesome-rsi
(lobehub) for the gain taxonomy, and RRSI, ModularRSI, SEABench, Agentic
Harness Engineering and the self-evolving-agent safety survey for the
specific guardrails. No code is copied.

RSI.md

@@ -0,0 +1,114 @@
+# Recursive self-improvement in ARTEX
+
+Status: measurement and shadow memory only. There is no harness search, no
+automatic adoption, and no self-modifying code in this repository.
+
+This file defines the contract any future harness-optimization work must meet,
+so the first experiment cannot quietly become an unguarded rewrite loop.
+
+## The three loops
+
+| loop | object | state |
+|---|---|---|
+| A. within a task | planner, worker, retester, adversarial gate | exists |
+| B. across tasks | evidence-gated lessons from closed tasks | shadow mode, PR #104 |
+| C. on the harness | prompts, skills, tool guidance | **not built**; this is its contract |
+
+Loop A produces task gain. Loop B is meant to produce retained gain: a lesson
+must survive a closed task and change a later one. Loop C is the only loop that
+can produce improver gain, and it is the only one that can silently damage the
+product, which is why it goes last.
+
+## Loop C contract
+
+Any PR that proposes, probes, or adopts harness edits must satisfy all of:
+
+1. **Live tasks propose, benchmarks adopt.** A successful bounty task can
+   generate a candidate lesson or edit, but it can never be the evidence for
+   adoption. Adoption requires held-out benchmark runs, because a live task is
+   unreproducible and contaminated by its target.
+2. **Owner approval per adoption.** The loop may prepare a proposal branch and
+   show the diff. It may not change the active prompt. Adoption is one explicit
+   owner action, like a baseline pin.
+3. **Immutable surfaces.** The following are never in the search space:
+   the adversarial and quality gates, scope and authorization checks,
+   prompt-injection defenses, tool allowlists, and the code-owned prompt tails
+   (traffic tools, artifact rules, lesson block). Only the editable prompt body,
+   skill markdown, and tool descriptions can be proposed.
+4. **One-step rollback.** Every adopted prompt change is a new
+   `agent_prompts` version, so rollback is a pointer change. Skills are files
+   under git; no adoption may bypass review.
+5. **Flag off by default.** The loop runs behind a feature flag. Turning it on
+   requires an owner decision, and the flag is checked per run.
+6. **Bounded edit budget.** A round may propose a bounded number of edits
+   (annealed over rounds). A critic proposes only edits that are expected to
+   transfer; a pruner rejects edits that only fit the probe task. This follows
+   RRSI (arXiv 2609.24972).
+7. **Attribution.** Probe results are compared against an unchanged baseline on
+   the same task and seed. Regressions are attributed to a specific module
+   rather than to the loop as a whole; the modular fault-localization idea is
+   from ModularRSI (arXiv 2609.14857). A paired evolving/non-evolving comparison
+   guards against misattributed safety regressions, following SEABench
+   (arXiv 2609.35596).
+8. **No self-approval and no silent state.** The loop cannot set its own status,
+   edit its own acceptance criteria, or write to the lesson library as
+   `adopted`. Lesson status changes stay owner actions.
+
+A future Loop C PR is acceptable only with:
+
+- a benchmark adapter and a held-out task set, independent of the tasks used to
+  propose the edit;
+- a baseline run and a candidate run with the same model, seed, budget, and
+  judge;
+- the judge independent of the subject model, with a falsification battery
+  (the existing L3 runner already enforces this);
+- per-gate results with denominators, not a single aggregate score;
+- a written rollback path and the flag name.
+
+## What the current layers do
+
+- `GET /api/tasks/{id}/outcome` (PR #102) records what a task produced and what
+  it cost: findings by disposition and severity, retest verdicts, tokens, tool
+  calls, skill misses, wall time.
+- `ARTEX_RSI_LESSONS=off|shadow|inject` (PR #104) extracts evidence-gated
+  lessons from terminal tasks and, in `inject` mode, appends a code-owned
+  data-not-instructions block after the planner and worker system prompts.
+  Status stays `candidate`.
+- `GET /api/skill-gaps` (PR #106) turns the existing miss ledger into a
+  capability backlog.
+
+None of these changes an agent's instructions on its own. Shadow mode exists to
+measure whether retrieval helps before any harness edit is attempted.
+
+## Credits
+
+The admission rule (no lesson without cue, action, and evidence) and the
+propose/probe/compose shape come from:
+
+> Harness^2: Recursive Agent Harnessing for an Open World.
+> Ruiyao Xu, Yanfei Chen, Zhongying CuiZhu, Bhavana Dalvi Mishra, Yifei Ming,
+> Han Yu, Rujun Han, Chen-Yu Lee, Tomas Pfister. arXiv:2610.14224, 2026.
+> Google Research. Apache-2.0. https://github.com/google-research/harness2
+
+The evidence taxonomy used in the design (task gain, retained gain, improver
+gain) and the implementation pointers come from:
+
+> awesome-rsi, lobehub. https://github.com/lobehub/awesome-rsi
+
+Specific ideas referenced above:
+
+- RRSI: Regularized Recursive Self-Improvement of Agent Harnesses,
+  arXiv:2609.24972 (annealed edit budget, critic and pruner).
+- ModularRSI: Modular and Generalizable Recursive Harness Self-Improvement,
+  arXiv:2609.14857 (module-level fault localization from success/failure
+  contrast).
+- SEABench: Benchmarking Endogenous Misalignment in Self-Evolving Agents,
+  arXiv:2609.35596 (paired evolving/non-evolving attribution).
+- Agentic Harness Engineering: Observability-Driven Automatic Evolution of
+  Coding-Agent Harnesses, arXiv:2604.25850 (observable edits with predictions
+  verified later, the same discipline as the benchmark gate here).
+- A Safety in Self-Evolving Agents survey, arXiv:2610.00093 (why properties
+  must survive accumulation and cross-context reuse, not just entry screening).
+
+Only ideas are borrowed. ARTEX code is independent Go and Python; no source
+from harness2 or the referenced projects is copied.

db/skill_gaps.go

@@ -1,51 +0,0 @@
-package db
-
-import "context"
-
-// SkillGap is one skill the agent asked for but the platform did not provide,
-// aggregated by skill, agent, and task category. A miss row is written when the
-// model names a skill that does not exist (skill_usage.found=false), so this
-// report is the evidence-backed capability backlog rather than a guess.
-type SkillGap struct {
-	Skill      string `json:"skill"`
-	AgentKey   string `json:"agent_key"`
-	CategoryID int64  `json:"category_id"`
-	Misses     int    `json:"misses"`
-	Hits       int    `json:"hits"`
-	LastSeen   int64  `json:"last_seen"`
-}
-
-// SkillGaps returns the aggregated miss report, highest miss count first.
-// Hits are the successful calls for the same key, so callers can compute a
-// miss rate without a second query.
-func (d *DB) SkillGaps(ctx context.Context, limit int) ([]SkillGap, error) {
-	if limit <= 0 {
-		limit = 50
-	}
-	rows, err := d.QueryContext(ctx, `
-		SELECT su.skill,
-		       COALESCE(su.agent_key,''),
-		       COALESCE(t.category_id,0),
-		       COUNT(*) FILTER (WHERE NOT su.found) AS misses,
-		       COUNT(*) FILTER (WHERE su.found)     AS hits,
-		       EXTRACT(EPOCH FROM MAX(su.ts))::bigint
-		FROM skill_usage su
-		LEFT JOIN tasks t ON t.id=su.task_id
-		GROUP BY 1,2,3
-		HAVING COUNT(*) FILTER (WHERE NOT su.found) > 0
-		ORDER BY misses DESC, 6 DESC, 1
-		LIMIT $1`, limit)
-	if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
-	out := []SkillGap{}
-	for rows.Next() {
-		var g SkillGap
-		if err := rows.Scan(&g.Skill, &g.AgentKey, &g.CategoryID, &g.Misses, &g.Hits, &g.LastSeen); err != nil {
-			return nil, err
-		}
-		out = append(out, g)
-	}
-	return out, rows.Err()
-}

server/server.go

@@ -673,7 +673,6 @@ func (s *Server) Handler() http.Handler {
 
 	mux.HandleFunc("GET /api/tasks", s.listTasks)
 	mux.HandleFunc("POST /api/tasks", s.createTask)
-	mux.HandleFunc("GET /api/skill-gaps", s.skillGaps)
 	mux.HandleFunc("GET /api/task-categories", s.pgListTaskCategories)
 	mux.HandleFunc("POST /api/task-categories", s.pgCreateTaskCategory)
 	mux.HandleFunc("PATCH /api/task-categories/{id}", s.pgRenameTaskCategory)

server/skill_gaps.go

@@ -1,30 +0,0 @@
-package server
-
-import (
-	"log"
-	"net/http"
-	"strconv"
-)
-
-// skillGaps reports skills the agent asked for but the platform did not
-// provide, aggregated by skill, agent, and task category. The source is the
-// existing skill_usage miss rows, so the backlog is evidence-backed rather than
-// inferred. Read-only: it creates no skill and changes no prompt.
-func (s *Server) skillGaps(w http.ResponseWriter, r *http.Request) {
-	limit := 50
-	if raw := r.URL.Query().Get("limit"); raw != "" {
-		n, err := strconv.Atoi(raw)
-		if err != nil || n < 1 || n > 500 {
-			writeErr(w, 400, "limit must be an integer between 1 and 500")
-			return
-		}
-		limit = n
-	}
-	gaps, err := s.m.PG().SkillGaps(r.Context(), limit)
-	if err != nil {
-		log.Printf("[skills] gap query failed: %v", err)
-		writeErr(w, 500, "skill gap query failed")
-		return
-	}
-	writeJSON(w, 200, map[string]any{"gaps": gaps, "count": len(gaps)})
-}

server/skill_gaps_test.go

@@ -1,107 +0,0 @@
-package server
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"strconv"
-	"testing"
-)
-
-func TestSkillGapsReport(t *testing.T) {
-	m, err := NewManager(t.TempDir(), "")
-	if err != nil {
-		t.Skipf("postgres unavailable (%v) — skipping", err)
-	}
-	defer m.Close()
-	task, err := m.CreateTask("skill gaps", "goal", nil, 0, 0)
-	if err != nil {
-		t.Fatal(err)
-	}
-	taskID, _ := strconv.ParseInt(task.ID, 10, 64)
-	defer func() { _ = m.pg.DeleteTask(taskID) }()
-	defer func() { _, _ = m.pg.Exec(`DELETE FROM skill_usage WHERE task_id=$1`, taskID) }()
-
-	if _, err := m.pg.Exec(`
-INSERT INTO skill_usage(skill,agent_key,task_id,found) VALUES
- ('rsi-test-graphql','worker',$1,false),
- ('rsi-test-graphql','worker',$1,false),
- ('rsi-test-graphql','worker',$1,true),
- ('rsi-test-cloud','worker',$1,false),
- ('rsi-test-known','worker',$1,true)`, taskID); err != nil {
-		t.Fatal(err)
-	}
-
-	s := New(context.Background(), m, t.TempDir(), t.TempDir(), t.TempDir())
-	token, err := signJWT(s.jwtKey)
-	if err != nil {
-		t.Fatal(err)
-	}
-	get := func(path string) *httptest.ResponseRecorder {
-		req := httptest.NewRequest(http.MethodGet, path, nil)
-		req.Header.Set("Authorization", "Bearer "+token)
-		rec := httptest.NewRecorder()
-		s.Handler().ServeHTTP(rec, req)
-		return rec
-	}
-
-	rec := get("/api/skill-gaps")
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status=%d body=%s", rec.Code, rec.Body.String())
-	}
-	var out struct {
-		Gaps []struct {
-			Skill    string `json:"skill"`
-			AgentKey string `json:"agent_key"`
-			Misses   int    `json:"misses"`
-			Hits     int    `json:"hits"`
-		} `json:"gaps"`
-		Count int `json:"count"`
-	}
-	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
-		t.Fatal(err)
-	}
-	bySkill := map[string]struct {
-		misses, hits int
-		agent        string
-	}{}
-	for _, g := range out.Gaps {
-		bySkill[g.Skill] = struct {
-			misses, hits int
-			agent        string
-		}{g.Misses, g.Hits, g.AgentKey}
-	}
-	if got := bySkill["rsi-test-graphql"]; got.misses != 2 || got.hits != 1 || got.agent != "worker" {
-		t.Fatalf("graphql gap=%+v want misses=2 hits=1 agent=worker", got)
-	}
-	if got := bySkill["rsi-test-cloud"]; got.misses != 1 {
-		t.Fatalf("cloud gap=%+v want misses=1", got)
-	}
-	if _, ok := bySkill["rsi-test-known"]; ok {
-		t.Fatal("a hit-only skill must not appear in the miss report")
-	}
-	first := out.Gaps[0].Skill
-	if first != "rsi-test-graphql" {
-		t.Fatalf("ordering: first=%q want rsi-test-graphql (highest misses)", first)
-	}
-
-	rec = get("/api/skill-gaps?limit=1")
-	if rec.Code != http.StatusOK {
-		t.Fatalf("limit status=%d body=%s", rec.Code, rec.Body.String())
-	}
-	var limited struct {
-		Gaps []struct {
-			Skill string `json:"skill"`
-		} `json:"gaps"`
-	}
-	if err := json.Unmarshal(rec.Body.Bytes(), &limited); err != nil {
-		t.Fatal(err)
-	}
-	if len(limited.Gaps) != 1 || limited.Gaps[0].Skill != "rsi-test-graphql" {
-		t.Fatalf("limit=1 returned %+v", limited.Gaps)
-	}
-	if rec := get("/api/skill-gaps?limit=abc"); rec.Code != http.StatusBadRequest {
-		t.Fatalf("bad limit status=%d want 400", rec.Code)
-	}
-}