@tachikomagundam/abathur 0.1.0

package/graders/historian/mutate.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Mutator wrapper for the historian live run (task 14). Invoked by the run-loop
+# as `bash mutate.sh <brief-file> <worktree> <model>` with cwd = the throwaway
+# launch worktree (reflect.ts contract). The REAL candidate source is a headless
+# `opencode run` child: it reads the reflection brief and proposes exactly one
+# mutation — a new markdown note under abathur-notes/ (never a sealed path;
+# kernel.immutableGlobs is enforced independently by the driver's PathPolicy).
+# The wrapper deterministically packages the model's note as a unified CREATE
+# diff (creation diffs have no context to drift) and appends a genome.jsonc
+# create-diff carrying the resolved spec bytes (plan 184: every sealed tree
+# must contain genome.jsonc so bundle export self-describes; plan 181 requires
+# it for the lineage). On unparseable model output the wrapper degrades to a
+# packaging-only candidate — honest, logged, never a fabricated mutation.
+set -uo pipefail
+brief_file="${1:?usage: mutate.sh <brief-file> <worktree> <model>}"
+worktree="${2:?usage: mutate.sh <brief-file> <worktree> <model>}"
+model="${3:?usage: mutate.sh <brief-file> <worktree> <model>}"
+canonical="${ABATHUR_GENOME_CANONICAL:?mutate.sh requires ABATHUR_GENOME_CANONICAL (resolved spec, canonical JSON)}"
+[ -f "$brief_file" ] || { echo "mutate: missing brief $brief_file" >&2; exit 1; }
+cp -f "$brief_file" "${ABATHUR_MUTATOR_RAW:-/tmp/abathur-mutate-raw.jsonl}.brief" 2>/dev/null || true
+[ -f "$canonical" ] || { echo "mutate: missing canonical spec $canonical" >&2; exit 1; }
+bin="${ABATHUR_OPENCODE_BIN:-opencode}"
+
+prompt="You are the genome mutator of the Abathur evolution harness. Read the reflection brief below (evidence from the incumbent bench of the historian wiki-skill genome). Propose exactly ONE improvement the genome owner can act on: create a NEW file under the path prefix abathur-notes/ (slug .md). Output ONLY a single JSON object, no prose, shape:
+{\"rationale\": \"<one sentence, <=400 chars>\", \"path\": \"abathur-notes/<slug>.md\", \"content\": \"<full markdown file contents>\"}
+Do not modify any other path. Scenarios, rubric.md, seed_sandbox.sh, baseline/ and README.md are immutable.
+
+BRIEF:
+$(cat "$brief_file")"
+
+raw="${ABATHUR_MUTATOR_RAW:-/tmp/abathur-mutate-raw.jsonl}"
+"$bin" run --model "$model" --format json --message "$prompt" >"$raw" 2>/dev/null
+rc=$?
+echo "mutate: opencode rc=$rc raw=$raw" >&2
+
+python3 - "$raw" "$canonical" "$rc" <<'PY'
+import json, re, sys
+
+raw, canonical_path, rc = sys.argv[1], sys.argv[2], int(sys.argv[3])
+
+def create_diff(path, text):
+    lines = text.split("\n")
+    if lines and lines[-1] == "":
+        lines.pop()
+    body = "".join("+" + ln + "\n" for ln in lines)
+    return f"--- /dev/null\n+++ b/{path}\n@@ -0,0 +1,{len(lines)} @@\n{body}"
+
+def last_text_events(path):
+    texts = []
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    ev = json.loads(line)
+                except ValueError:
+                    continue
+                part = ev.get("part") or {}
+                if ev.get("type") == "text" and isinstance(part.get("text"), str):
+                    texts.append(part["text"])
+    except FileNotFoundError:
+        pass
+    return texts
+
+proposal = None
+for text in reversed(last_text_events(raw)):
+    candidate = text.strip()
+    fence = re.search(r"```(?:json)?\s*(\{.*\})\s*```", candidate, re.S)
+    if fence:
+        candidate = fence.group(1)
+    start, end = candidate.find("{"), candidate.rfind("}")
+    if start < 0 or end <= start:
+        continue
+    try:
+        doc = json.loads(candidate[start : end + 1])
+    except ValueError:
+        continue
+    if isinstance(doc, dict):
+        proposal = doc
+        break
+
+spec_text = open(canonical_path, encoding="utf-8").read()
+packaging = create_diff("genome.jsonc", spec_text if spec_text.endswith("\n") else spec_text + "\n")
+
+if isinstance(proposal, dict):
+    path = proposal.get("path")
+    content = proposal.get("content")
+    rationale = proposal.get("rationale")
+    if (
+        isinstance(path, str)
+        and re.fullmatch(r"abathur-notes/[a-z0-9][a-z0-9._-]{0,63}\.md", path)
+        and isinstance(content, str)
+        and 0 < len(content) < 200000
+        and isinstance(rationale, str)
+        and 0 < len(rationale) <= 4000
+        and "\x00" not in content
+    ):
+        content = content.replace("\r", "")
+        if not content.endswith("\n"):
+            content += "\n"
+        candidate = {"id": "mutate-live", "rationale": rationale, "diffs": [create_diff(path, content), packaging]}
+        print(json.dumps({"candidates": [candidate]}))
+        sys.exit(0)
+
+print(json.dumps({
+    "candidates": [{
+        "id": "mutate-package-only",
+        "rationale": "packaging-only candidate: model output unparseable or path rejected (opencode rc=%d); lineage genome.jsonc added, no skill mutation proposed" % rc,
+        "diffs": [packaging],
+    }]
+}))
+PY

package/graders/historian/reset-sandbox.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Reset hook (task 14, closes Metis #3): historian's seed_sandbox.sh SKIPs
+# existing pages, so a mutated/consumed _sandbox fixture never self-restores.
+# resetCommand deletes EVERY _sandbox/* page by id (wiki-ops hard delete) and
+# refreshes the wiki cache, making back-to-back generations state-equal.
+# Runs with cwd = the unit sandbox, HOME = sandbox home (key installed by the
+# seed wrapper; mirrorSandboxHome rebuilds the home on reset too, so ensure it).
+set -euo pipefail
+base="${ABATHUR_WIKI_BASE:?reset-sandbox.sh requires ABATHUR_WIKI_BASE in env}"
+ops="${ABATHUR_WIKI_OPS:?reset-sandbox.sh requires ABATHUR_WIKI_OPS in env}"
+key="${ABATHUR_WIKI_KEY_FILE:-}"
+if [ -n "$key" ] && [ -f "$key" ] && [ ! -f "$HOME/.wikijs-api-key" ]; then
+  mkdir -p "$HOME"
+  install -m 600 "$key" "$HOME/.wikijs-api-key"
+fi
+[ -f "$HOME/.wikijs-api-key" ] || { echo "reset-sandbox: no wiki key at $HOME/.wikijs-api-key" >&2; exit 1; }
+n=0
+while read -r id; do
+  [ -n "$id" ] || continue
+  if ! python3 "$ops" delete "$id" --confirm >/dev/null 2>&1; then
+    # A parent delete cascades to its children: tolerate iff the row is really gone.
+    if python3 - "$base" "$id" <<'GONE'
+import json, pathlib, sys, urllib.request
+base, pid = sys.argv[1].rstrip("/"), int(sys.argv[2])
+token = open(pathlib.Path.home() / ".wikijs-api-key").read().strip()
+req = urllib.request.Request(
+    base + "/graphql",
+    data=json.dumps({"query": "{ pages { single(id: %d) { id } } }" % pid}).encode(),
+    headers={"Content-Type": "application/json", "Authorization": "Bearer " + token},
+)
+doc = json.load(urllib.request.urlopen(req, timeout=20))
+single = (doc.get("data") or {}).get("pages") or {}
+raise SystemExit(0 if single.get("single") is None else 1)
+GONE
+    then
+      echo "reset-sandbox: page $id already gone (cascade)" >&2
+    else
+      echo "reset-sandbox: delete $id failed" >&2
+      exit 1
+    fi
+  fi
+  n=$((n + 1))
+done < <(python3 - "$base" <<'PY'
+import json, pathlib, sys, urllib.request
+base, token = sys.argv[1].rstrip("/"), open(pathlib.Path.home() / ".wikijs-api-key").read().strip()
+req = urllib.request.Request(
+    base + "/graphql",
+    data=json.dumps({"query": "{ pages { list { id path } } }"}).encode(),
+    headers={"Content-Type": "application/json", "Authorization": "Bearer " + token},
+)
+doc = json.load(urllib.request.urlopen(req, timeout=20))
+if "errors" in doc:
+    raise SystemExit("reset-sandbox: graphql %s" % json.dumps(doc["errors"])[:200])
+for r in doc["data"]["pages"]["list"]:
+    if r["path"] == "_sandbox" or r["path"].startswith("_sandbox/"):
+        print(r["id"])
+PY
+)
+python3 "$ops" cache-refresh >/dev/null 2>&1 || true
+echo "reset-sandbox: deleted $n _sandbox page(s), cache refreshed"

package/graders/historian/run-scenario.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Run hook (task 14): spawn the scenario agent headless, record the transcript
+# at $ABATHUR_TRANSCRIPT (adapter contract, plan line 120), and print the last
+# stdout line {tokensEst, turns} for parseRunMeta. opencode is invoked exactly
+# as historian's README prescribes: `opencode run --command historian --message
+# "<scenario Brief>"` — the Brief section of the scenario file is the prompt.
+# --auto auto-approves the plugin tools (the wiki sandbox is the blast radius;
+# kernel seals + _sandbox-only writes bound it, plan todo 14).
+set -euo pipefail
+unit_id="${1:?usage: run-scenario.sh <unitId> <scenario-file>}"
+scenario_file="${2:?usage: run-scenario.sh <unitId> <scenario-file>}"
+[ -f "$scenario_file" ] || { echo "run-scenario: missing scenario file $scenario_file" >&2; exit 2; }
+[ -n "${ABATHUR_TRANSCRIPT:-}" ] || { echo "run-scenario: ABATHUR_TRANSCRIPT not set" >&2; exit 2; }
+key="${ABATHUR_WIKI_KEY_FILE:-}"
+if [ -n "$key" ] && [ -f "$key" ] && [ ! -f "$HOME/.wikijs-api-key" ]; then
+  mkdir -p "$HOME"
+  install -m 600 "$key" "$HOME/.wikijs-api-key"
+fi
+bin="${opencodeBin:-opencode}"
+brief="$(awk '/^##[[:space:]]*Brief/{f=1;next} f && /^## /{exit} f' "$scenario_file")"
+[ -n "$brief" ] || { echo "run-scenario: empty Brief section in $scenario_file" >&2; exit 2; }
+mkdir -p "$(dirname "$ABATHUR_TRANSCRIPT")"
+status=0
+"$bin" run --command historian --auto --format json --message "$brief" >"$ABATHUR_TRANSCRIPT" 2>/dev/null || status=$?
+python3 - "$ABATHUR_TRANSCRIPT" "$unit_id" "$status" <<'PY'
+import json, sys
+path, unit, status = sys.argv[1], sys.argv[2], int(sys.argv[3])
+tokens = turns = 0
+try:
+    with open(path, encoding="utf-8", errors="replace") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                ev = json.loads(line)
+            except ValueError:
+                continue
+            part = ev.get("part") or {}
+            if ev.get("type") == "step_finish" or part.get("type") == "step-finish":
+                turns += 1
+                total = (part.get("tokens") or {}).get("total")
+                if isinstance(total, (int, float)):
+                    tokens += int(total)
+except FileNotFoundError:
+    pass
+print(json.dumps({"unit": unit, "tokensEst": tokens, "turns": turns, "opencodeExit": status}))
+PY
+exit 0

package/graders/historian/seed-wrapped.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Seed hook wrapper (task 14). The fixture adapter runs hooks with
+# HOME=<sandbox>/.sandbox-home; wiki-ops and historian's seed_sandbox.sh read
+# ~/.wikijs-api-key, so the key must land in the sandbox home first. Then the
+# genome repo's own seed_sandbox.sh runs unchanged (plan: seedCommand →
+# seed_sandbox.sh), and the post-seed wiki snapshot is recorded to
+# .bench/wiki-pre.json — the grader diffs created/updated/deleted against it.
+set -euo pipefail
+real_seed="${1:?usage: seed-wrapped.sh <path-to-seed_sandbox.sh>}"
+[ -f "$real_seed" ] || { echo "seed-wrapped: missing $real_seed" >&2; exit 1; }
+base="${ABATHUR_WIKI_BASE:?seed-wrapped.sh requires ABATHUR_WIKI_BASE in env}"
+key="${ABATHUR_WIKI_KEY_FILE:-}"
+if [ -n "$key" ] && [ -f "$key" ] && [ ! -f "$HOME/.wikijs-api-key" ]; then
+  mkdir -p "$HOME"
+  install -m 600 "$key" "$HOME/.wikijs-api-key"
+fi
+bash "$real_seed"
+mkdir -p .bench
+python3 - "$base" > .bench/wiki-pre.json <<'PY'
+import json, os, pathlib, sys, urllib.request
+base, token = sys.argv[1].rstrip("/"), open(pathlib.Path.home() / ".wikijs-api-key").read().strip()
+req = urllib.request.Request(
+    base + "/graphql",
+    data=json.dumps({"query": "{ pages { list { id path locale updatedAt } } }"}).encode(),
+    headers={"Content-Type": "application/json", "Authorization": "Bearer " + token},
+)
+doc = json.load(urllib.request.urlopen(req, timeout=20))
+if "errors" in doc:
+    raise SystemExit("wiki-pre: graphql %s" % json.dumps(doc["errors"])[:200])
+print(json.dumps(doc["data"]["pages"]["list"]))
+PY
+echo "seed-wrapped: wiki-pre.json rows=$(python3 -c 'import json;print(len(json.load(open(".bench/wiki-pre.json"))))')"

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@tachikomagundam/abathur",
+  "version": "0.1.0",
+  "description": "Evolution harness: observe failures, mutate, re-bench, select — human-gated promotion, offline lineage bundles.",
+  "author": "TachikomaGundam",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TachikomaGundam/Abathur.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TachikomaGundam/Abathur/issues"
+  },
+  "homepage": "https://github.com/TachikomaGundam/Abathur#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "abathur": "dist/cli.js"
+  },
+  "main": "dist/cli.js",
+  "files": [
+    "dist",
+    "config",
+    "graders",
+    "docs",
+    ".github"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/copy-assets.mjs",
+    "test": "npm run build && node --test \"dist/test/**/*.test.js\"",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0"
+  }
+}