@tachikomagundam/abathur 0.2.6 → 0.2.8

package/graders/pcb-agent/mutate.sh

@@ -0,0 +1,165 @@
+#!/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 RUN CARD under abathur-notes/ (never a sealed path;
+# kernel.immutableGlobs is enforced independently by the driver's PathPolicy).
+# Run cards are the delivery seam (S4): run-scenario.sh appends them VERBATIM to
+# every scenario brief under a `## Run card` heading, so a candidate tree's
+# mutation genuinely steers the benched agent and score deltas are attributable.
+# The wrapper deterministically packages the model's run card 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>}"
+# the published engine does not export ABATHUR_GENOME_CANONICAL; derive from the
+# launch worktree's own genome.jsonc (written by the engine each round). Env wins
+# when present; missing-both still fail-closes on the [ -f "$canonical" ] guard.
+canonical="${ABATHUR_GENOME_CANONICAL:-$worktree/genome.jsonc}"
+[ -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}"
+
+ptfile="$(mktemp /tmp/abathur-mutate-prompt.XXXXXX)"
+cat > "$ptfile" <<'PROMPT_EOF'
+You are the genome mutator of the Abathur evolution harness, PCB-agent lane. Read the reflection brief below (evidence from the incumbent bench of the pcb-agent genome: the PCB team run log, FINDINGS.md, and the grader OUTCOME/EYES metrics). Propose exactly ONE improvement: create a NEW RUN CARD under abathur-notes/ (slug .md). The run card is appended VERBATIM to the team task brief at bench time — write direct, actionable engineering guidance the PCB orchestrator team can follow. TARGET THE EYES GAP: if the grader shows traps the team hit but never NAMED (trap_coverage low while outcome partial), the card must teach the DISCOVERY PROCEDURE (how to notice this class of defect yourself), not the pasted answer — an answer scores once and dies; a discovery method evolves the team. Prefer converting one observed failure into a check the team can run itself. 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/, README.md and genome.jsonc are immutable; board tooling lives in the arena, not the genome tree.
+
+BRIEF:
+PROMPT_EOF
+cat "$brief_file" >> "$ptfile"
+prompt="$(cat "$ptfile")"
+rm -f "$ptfile"
+
+raw="${ABATHUR_MUTATOR_RAW:-/tmp/abathur-mutate-raw.jsonl}"
+"$bin" run --model "$model" --format json -- "$prompt" >"$raw" 2>/dev/null
+rc=$?
+echo "mutate: opencode rc=$rc raw=$raw" >&2
+
+python3 - "$raw" "$canonical" "$rc" "$worktree" <<'PY'
+import json, os, re, sys
+
+raw, canonical_path, rc, worktree = sys.argv[1], sys.argv[2], int(sys.argv[3]), sys.argv[4]
+
+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)
+    end = candidate.rfind("}")
+    if end < 0:
+        continue
+    # prose preambles can contain set-notation braces like {症状/Symptoms, ...} —
+    # the first '{' is not necessarily JSON; try every open brace from the LAST
+    # backwards so the outermost-to-last-close object wins when one parses.
+    opens = [i for i, ch in enumerate(candidate) if ch == "{" and i < end]
+    doc = None
+    for start in reversed(opens):
+        try:
+            parsed = json.loads(candidate[start : end + 1])
+        except ValueError:
+            continue
+        if isinstance(parsed, dict):
+            doc = parsed
+            break
+    if doc is not None:
+        proposal = doc
+        break
+
+spec_text = open(canonical_path, encoding="utf-8").read()
+if not spec_text.endswith("\n"):
+    spec_text += "\n"
+# genome.jsonc in the base tree was written by this wrapper's own prior round,
+# so a replace-all modify hunk always anchors deterministically at line 1.
+# A CREATE here would break apply the moment the file lands in the base (udiff
+# refuses create-over-existing and discards the WHOLE candidate).
+gen_path = os.path.join(worktree, "genome.jsonc")
+try:
+    with open(gen_path, encoding="utf-8") as fh:
+        base_text = fh.read()
+except FileNotFoundError:
+    packaging = create_diff("genome.jsonc", spec_text)
+except OSError as err:
+    sys.stderr.write("mutate: genome.jsonc unreadable: %s\n" % err)
+    sys.exit(3)
+else:
+    if base_text == spec_text:
+        packaging = None
+    else:
+        base_body = base_text.split("\n")
+        if base_body and base_body[-1] == "":
+            base_body.pop()
+        old_h = "".join("-" + ln + "\n" for ln in base_body)
+        new_h = "".join("+" + ln + "\n" for ln in spec_text.split("\n")[:-1])
+        packaging = (
+            "--- a/genome.jsonc\n+++ b/genome.jsonc\n"
+            "@@ -1,%d +1,%d @@\n%s%s" % (len(base_body), len(spec_text.split("\n")) - 1, old_h, new_h)
+        )
+
+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"
+        diffs = [create_diff(path, content)] + ([packaging] if packaging else [])
+        candidate = {"id": "mutate-live", "rationale": rationale, "diffs": diffs}
+        print(json.dumps({"candidates": [candidate]}))
+        sys.exit(0)
+
+if packaging:
+    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],
+        }]
+    }))
+else:
+    print(json.dumps({"candidates": []}))
+PY

package/graders/pcb-agent/r20-bench.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# r20 production-topology bench sandbox: runs a command INSIDE bwrap where the
+# arena is bind-mounted AT the control literal, with host-vendored dirs re-bound
+# over the arena's excluded gaps (bind-mounts stack: later wins).
+# Usage: r20-bench.sh <arena> -- <inner command...>
+set -euo pipefail
+ARENA="${1:?arena}"; shift; [ "${1:-}" = "--" ] && shift
+SRC=/home/lab/workspace/pcb-control
+LIT=$SRC   # the literal path the control plane believes itself to be
+# v8 netns ABANDONED: lo cannot be raised in this unprivileged userns (EPERM).
+# Isolation strategy instead: arena bind at the literal (fs) + PCB_PRODUCTION_SERVE_PORT
+# exported to a FREE host port (net coexistence; data dirs are the arena's, so the
+# bench serve cannot touch the real lane state; verified by G5 record tuple).
+PORT=$(python3 -c "import socket;s=socket.socket();s.bind((\"127.0.0.1\",0));print(s.getsockname()[1]);s.close()")
+ARGS=(--ro-bind / / --dev-bind /dev /dev --proc /proc --bind /tmp /tmp
+      --bind "$ARENA" "$LIT" --unshare-pid --setenv PCB_PRODUCTION_SERVE_PORT "$PORT")
+# vendored opencode binary (excluded from arena tar; must appear AT the literal)
+ARGS+=(--ro-bind "$SRC/profiles/production/bin" "$LIT/profiles/production/bin")
+# every vendored node_modules under the control tree (typescript for the loader,
+# production-home caches carrying OMO/ACP/HR packages) — ro at their literals
+while IFS= read -r -d '' d; do
+  rel="${d#$SRC}"
+  [ -d "$ARENA$rel" ] && continue   # arena copy exists: leave it (candidate-owned)
+  mkdir -p "$ARENA$(dirname "$rel")" 2>/dev/null || true
+  ARGS+=(--ro-bind "$d" "$LIT$rel")
+done < <(find "$SRC" -maxdepth 6 -name node_modules -type d -print0)
+exec bwrap "${ARGS[@]}" -- /bin/bash -c "$*"

package/graders/pcb-agent/reset-sandbox.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Reset hook (pcb-agent): honest no-op. Freshness is guaranteed at run time —
+# run-scenario.sh re-seeds the arena (rm -rf + copy pristine starter kit) at the
+# top of EVERY rep, so back-to-back generations are state-equal without a
+# separate wipe. Kept as an explicit file so the contract is visible, not empty.
+set -euo pipefail
+echo "RESET-NOOP (per-rep reseed happens in run-scenario.sh)"

package/graders/pcb-agent/run-scenario-r20.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# r20 run-scenario v2 — PRODUCTION-TOPOLOGY bench (user ruling 2026-09-30:
+# "我工作环境里是要用PCB-Orchestrator这个角色来执行的"). One rep = fresh arena
+# (per-rep reseed is the L2 reset AND the pollution guard: smoke runs mutate the
+# copied opencode.db/config and can drift G1), bwrap quarantine at the control
+# literal, launcher-gated serve on a free port (netns impossible: lo EPERM),
+# scenario driven as a REAL pcb-orchestrator session over REST, transcript +
+# control-plane ledger harvested with literal->arena path mapping for the grader.
+# Usage: run-scenario-r20.sh <unit-id> <scenario-file> <genome-repo> [arena-root]
+set -uo pipefail
+UNIT="$1"; SCENARIO="$2"; GENOME_REPO="$3"; ARENA="${4:-/tmp/r20-arena-$UNIT}"
+GRAD=/home/lab/workspace/harness/Abathur/graders/pcb-agent
+LIT=/home/lab/workspace/pcb-control
+OUT="$GENOME_REPO/.omo/run-artifacts/$UNIT"; mkdir -p "$OUT"
+BRIEF_FILE="$OUT/brief.md"; cp "$SCENARIO" "$BRIEF_FILE"
+
+bash "$GRAD/seed-r20-arena.sh" "$ARENA" "$GENOME_REPO" > "$OUT/seed.log" 2>&1 || { echo "SEED_FAIL" > "$OUT/infra.fail"; exit 1; }
+
+# candidate role files: seed copied $GENOME_REPO/agents/*.md over all three trees (v4 seam)
+
+cat > "$OUT/inner.sh" <<'INNER'
+set -x
+L=/home/lab/workspace/pcb-control
+OUTD=__OUT__
+PORT=${PCB_PRODUCTION_SERVE_PORT}
+cd $L/production-console
+export HOME=$L/production-home
+timeout ${PCB_REP_TIMEOUT:-1500} $L/tools/start_production_orchestrator_ui.sh --serve $PORT > $OUTD/serve.log 2>&1 &
+SPID=$!
+OK=0
+for i in $(seq 1 150); do sleep 3
+  curl -s --max-time 2 http://127.0.0.1:$PORT/session >/dev/null 2>&1 && { OK=1; break; }
+  kill -0 $SPID 2>/dev/null || break
+done
+[ "$OK" = 1 ] || { echo "SERVE_UP=0" > $OUTD/infra.fail; kill $SPID 2>/dev/null; exit 1; }
+$L/tools/start_production_orchestrator_ui.sh --probe $PORT 2>&1 | tail -1 > $OUTD/probe.txt
+SID=$(curl -s --max-time 10 -X POST http://127.0.0.1:$PORT/session -H 'content-type: application/json' -d "{\"title\":\"bench-$UNIT\"}" | python3 -c "import json,sys;print(json.load(sys.stdin).get('id',''))")
+# r21: named bench-approver arm (reactive H-gate stand-in, append-only audit log)
+setsid nohup python3 /home/lab/workspace/harness/Abathur/graders/pcb-agent/bench-approver.py \
+  http://127.0.0.1:$PORT "$SID" $OUTD/approve-log.jsonl ${PCB_TURN_TIMEOUT:-1200} >/dev/null 2>&1 &
+APPR=$!
+python3 - "$OUTD" "$BRIEF_FILE" <<'PYMSG' > $OUTD/payload.json
+import json, sys
+outd, brief = sys.argv[1], sys.argv[2]
+msg = open(brief).read()
+json.dump({"agent": "pcb-orchestrator",
+           "model": {"providerID": "local-qwen", "modelID": "qwen3.8-flash-next"},
+           "parts": [{"type": "text", "text": msg}]}, open(outd + "/payload_body.json", "w"))
+PYMSG
+timeout ${PCB_TURN_TIMEOUT:-1200} curl -s --max-time ${PCB_TURN_TIMEOUT:-1200} -X POST "http://127.0.0.1:$PORT/session/$SID/message" -H 'content-type: application/json' -d @$OUTD/payload_body.json > $OUTD/transcript.json
+echo "$SID" > $OUTD/session-id
+kill $SPID $APPR 2>/dev/null
+[ -s $OUTD/transcript.json ] || { echo "EMPTY_TRANSCRIPT" > $OUTD/infra.fail; exit 1; }
+INNER
+sed -i "s#__OUT__#/tmp/r20-out-$UNIT#g" "$OUT/inner.sh"  # sandbox-writable; harvested after
+mkdir -p /tmp/r20-out-$UNIT && rm -f /tmp/r20-out-$UNIT/*
+
+# r20-bench.sh builds the full mount table (bin + every vendored node_modules
+# literal-stack + free-port env). inner.sh reads $PCB_PRODUCTION_SERVE_PORT.
+timeout $(( ${PCB_REP_TIMEOUT:-1500} + 900 )) bash "$GRAD/r20-bench.sh" "$ARENA" -- \
+  "BRIEF_FILE=$BRIEF_FILE bash $OUT/inner.sh" > "$OUT/inner.log" 2>&1
+RC=$?
+cp -f /tmp/r20-out-$UNIT/* "$OUT/" 2>/dev/null || true
+# node_modules literal-stack binds (arena lacks them by design)
+# harvest: map the control literal back to the arena for the grader
+python3 - "$OUT" "$ARENA" "$LIT" <<'PYH' 2>/dev/null || true
+import json, os, re, sys
+out, arena, lit = sys.argv[1:4]
+t = os.path.join(out, "transcript.json")
+if os.path.exists(t):
+    s = open(t, errors="replace").read().replace(lit, arena)
+    open(t, "w").write(s)
+PYH
+cp -f "$ARENA"/state/capabilities/*.json "$OUT/" 2>/dev/null || true
+find "$ARENA/state" -name 'denied-*' -newer "$OUT/seed.log" 2>/dev/null | head -20 > "$OUT/ledger-rows.txt"
+echo "r20-rep rc=$RC unit=$UNIT arena=$ARENA out=$OUT"
+exit $RC

package/graders/pcb-agent/run-scenario.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# run-scenario.sh (pcb-agent) — spawn the PCB TEAM headless on the scenario brief.
+# The seat writes ZERO board artifacts here: this script only (1) seeds an isolated
+# arena, (2) launches the internal-control orchestrator profile (isolated HOME/DB per
+# L-isolation) with the brief, (3) records the transcript. All engineering is done by
+# the team's own agents. Transcript = the evidence the grader reads.
+#
+# Contract mirrors historian: argv = <unitId> <scenario-file> [repoRoot]; last stdout
+# line = {"tokensEst":N,"turns":M} for parseRunMeta; ABATHUR_TRANSCRIPT honored.
+set -euo pipefail
+unit_id="${1:?usage: run-scenario.sh <unitId> <scenario-file> [repoRoot]}"
+scenario_file="${2:?scenario file}"
+repo_root="${3:-$(dirname "$(dirname "$scenario_file")")}"
+HERE="$(cd "$(dirname "$0")" && pwd)"
+CONTROL=/home/lab/workspace/pcb-control
+ARENA_ROOT="${PCB_BENCH_ARENA:-/tmp/opencode/pcb-bench}"
+ARENA="$ARENA_ROOT/$unit_id"
+TRANSCRIPT="${ABATHUR_TRANSCRIPT:-$ARENA_ROOT/$unit_id.transcript.jsonl}"
+mkdir -p "$ARENA_ROOT"
+
+bash "$HERE/seed-sandbox.sh" "$ARENA" "$HERE/seed"
+
+# Brief = the scenario file (whole thing; it is the task card, no solutions inside).
+BRIEF="$(cat "$scenario_file")"
+# run cards (S4 seam, historian precedent): candidate mutations ride to the team verbatim.
+rc=""
+if [ -d "$repo_root/abathur-notes" ]; then
+  for n in "$repo_root"/abathur-notes/*.md; do [ -e "$n" ] || continue
+    rc="$rc
+## Run card
+$(cat "$n")"; done
+fi
+
+cd "$ARENA"
+# per-unit isolated HOME/DB (never the human main DB; L-isolation law), seeded
+# from the PROVISIONED internal home's provider config (local-qwen baseURL etc).
+UHOME="$ARENA_ROOT/$unit_id.home"; rm -rf "$UHOME"; mkdir -p "$UHOME/.config" "$UHOME/.local/share/opencode"
+cp -r /home/lab/workspace/pcb-control/internal-home/.config/opencode "$UHOME/.config/" 2>/dev/null || true
+rm -rf "$UHOME/.config/opencode/node_modules" "$UHOME/.local/share/opencode/opencode.db" 2>/dev/null || true
+DB="$UHOME/.local/share/opencode/opencode.db"
+
+# THE TEAM IS THE SUBJECT: mount the PCB role tree into the arena cwd so
+# `--agent pcb-orchestrator` resolves. Role provenance is the genome seam:
+# if the candidate tree carries agents/*.md (a mutation to the team itself),
+# those files WIN over the canonical internal-control copies.
+mkdir -p "$ARENA/.opencode/agents"
+cp /home/lab/workspace/pcb-control/internal-control/.opencode/agents/*.md "$ARENA/.opencode/agents/"
+if [ -d "$repo_root/agents" ] && ls "$repo_root"/agents/*.md >/dev/null 2>&1; then
+  cp -f "$repo_root"/agents/*.md "$ARENA/.opencode/agents/"
+  echo "role-provenance: candidate-tree agents override canonical" >&2
+fi
+
+RUNENV=(env -i PATH="$PATH" LANG=C.UTF-8 TERM=xterm-256color HOME="$UHOME"
+  XDG_DATA_HOME="$UHOME/.local/share" XDG_CACHE_HOME="$UHOME/.cache" XDG_STATE_HOME="$UHOME/.local/state"
+  OPENCODE_DB="$DB" KICAD_SHARE_DIR=/home/lab/.local/AppDir/share/kicad)
+
+# FAIL-CLOSED SELF-PROOF GATE: the named agent must actually resolve BEFORE we
+# spend a rep. "agent not found. Falling back to default" voids the rep — that
+# is precisely the channel-dead noise theater the lane forbids.
+"${RUNENV[@]}" opencode agent list >"$ARENA/.agent-list.txt" 2>&1
+grep -q "pcb-orchestrator" "$ARENA/.agent-list.txt" || {
+  echo "RUNNER_GATE_FAIL: pcb-orchestrator not in resolved agent inventory" >&2
+  tail -5 "$ARENA/.agent-list.txt" >&2
+  exit 1
+}
+
+timeout "${PCB_RUN_TIMEOUT:-2400}" "${RUNENV[@]}" \
+  opencode run --agent pcb-orchestrator --format json \
+  --dir "$ARENA" -- "$BRIEF$rc" > "$TRANSCRIPT" 2>"$ARENA/.run-stderr" || true
+
+if [ ! -s "$TRANSCRIPT" ]; then
+  echo "RUNNER_INFRA_FAIL: empty transcript (see $ARENA/.run-stderr)" >&2
+  exit 1
+fi
+# mechanical role attribution proof: the bench session in the isolated DB MUST
+# be owned by pcb-orchestrator (transcript lines carry no agent field; the DB
+# session table does). No proof = void rep, never a scored fallback run.
+ROLE_OK="$(sqlite3 "$DB" "SELECT COUNT(*) FROM session WHERE agent='pcb-orchestrator';" 2>/dev/null || echo 0)"
+[ "${ROLE_OK:-0}" -ge 1 ] || { echo "RUNNER_INFRA_FAIL: no pcb-orchestrator session in $DB (fallback-agent run would be noise theater)" >&2; exit 1; }
+
+turns=$(grep -c '"type":"text"' "$TRANSCRIPT" 2>/dev/null || true); turns="${turns:-0}"
+tokens=$(python3 - "$TRANSCRIPT" <<'EOF' 2>/dev/null | tail -1 || true
+import json,sys
+n=0
+for l in open(sys.argv[1]):
+    try: d=json.loads(l)
+    except Exception: continue
+    p=d.get("part",{})
+    if p.get("type")=="text": n+=len(p.get("text",""))
+print(n//4)
+EOF
+); tokens="${tokens:-0}"
+echo "arena=$ARENA" > "$ARENA_ROOT/$unit_id.arena"
+python3 -c "import json,re;t=int(re.sub(r'[^0-9]','',str('$tokens')) or 0);u=int(re.sub(r'[^0-9]','',str('$turns')) or 0);print(json.dumps({'tokensEst':t,'turns':u}))"

package/graders/pcb-agent/seed/esp32s3-r12-BRIEF.txt

@@ -0,0 +1,51 @@
+# MODULE BRIEF -- esp32s3-r12 (fixture-tier mini-board)
+
+Mission dir: fixtures/board-lab/esp32s3-r12/ (root: /home/lab/workspace/pcb-control/fixtures)
+Binding plan: 2ee2cfb309bea8552dd294db3eb087d74950f0e82e0e11524a142c9f8f217f4a / dispatch pcb-dispatch-r12a-plan1
+
+## 0. Purpose
+Six-module ESP32-S3 breakout: USB-C 5V in -> ME6211 3.3V LDO -> module power/decoupling, one status LED, one 1x4 debug header with UART. Fixtures only; never the real board.
+
+## 1. Netlist (exactly 6 nets)
+- +3V3  : U1.3V3, U2.VOUT, C1.1, C2.1, C3.1, D1.anode, H1.1   (L10: single merged name, no variants)
+- +5V_IN: J1.VBUS, U2.VIN
+- GND   : J1.GND, U2.GND, C1.2, C2.2, C3.2, R1.2? NO -> R1.2 is +3V3 per LED string below.
+  Correction -- GND: J1.GND, U2.GND, C1.2, C2.2, C3.2, D1... see M5 for string orientation.
+- GPIO2 : U1.GPIO2, R1.2
+- GPIO4 : U1.GPIO4, H1.2 (label "TX" = board->host)
+- GPIO5 : U1.GPIO5, H1.3 (label "RX" = host->board)
+Final GND set: J1.GND, U2.GND, C1.2, C2.2, C3.2, H1.4.
+All other U1 pins NC; flash/PSRAM GPIO26-32 MUST remain unconnected. U1.EN tied directly to +3V3 (hard-enable; accepted fixture deviation, flagged for DFM review).
+
+## 2. Modules (6 max -- no extra refs permitted)
+- M1 U1 ESP32-S3-WROOM-1 (module). Power pads 3V3/GND per library footprint; IO used: EN, GPIO2, GPIO4 (UART TX), GPIO5 (UART RX).
+- M2 J1 USB-C receptacle, power-only. Connect VBUS(A4/A9/B4/B5 bussed)->+5V_IN and GND only. CC1/CC2 left NC -- fixture is bench/charger-fed; no PD negotiation. Deviation noted for reviewer.
+- M3 U2 ME6211C33 LDO (SOT-23-3 class). Function pins VIN->+5V_IN, GND->GND, VOUT->+3V3. Pad-number resolution against the project library symbol is the schematic agent's job, verified by gate.
+- M4 Decoupling: C1,C2 100nF 0402 across +3V3/GND placed at U1 3V3 pad(s); C3 10uF 0603 across +3V3/GND at U2 VOUT. ME6211 input cap omitted (fixture simplification, flagged).
+- M5 Status: +3V3 -> D1 anode, D1 cathode -> R1 (1k) -> GPIO2 (sink-driven, active-low lit). GPIO2 is not an S3 strapping pin (straps are 0/3/45/46): safe.
+- M6 H1 1x4 header, 2.54mm pitch: pin1 +3V3, pin2 GPIO4/TX, pin3 GPIO5/RX, pin4 GND.
+
+## 3. Explicit rules -- binding on brief AND every downstream artifact
+- L10 ONE merged power net named +3V3 for every 3.3V pad. Forbidden: +3V3A, 3V3_D, VDD_3V3, duplicate 3.3V names. Net-name scan of sch+pcb must find exactly "+3V3".
+- L11 Every footprint pad pitch AND courtyard gap >= 0.25mm (class clearance 0.2mm + 0.05 margin). 0402 pads 1.0x0.5mm, rot-aware: clearance check applies after per-ref rotation. U1 side pads on >=1.5mm vertical grid rows.
+- L16 Netlist uses KiCad schematic global-label grammar: every connection is a wire terminating in a label whose text equals the net name, placed at each pin. No hierarchical/local-only labels, no net-naming-by-wire.
+- L1 pos.csv refs == bom.csv refs exactly (same set, same strings): {U1,U2,J1,H1,C1,C2,C3,D1,R1} -- 10 refs, no suffix drift, no extra/missing.
+- Placement grid: 0.5mm snap for all component origins.
+
+## 4. Artifact contract (mission dir)
+- esp32s3-r12.kicad_sch -- 10 symbols, nets per section 1, grammar per L16.
+- esp32s3-r12.kicad_pcb -- footprints from project lib; courtyard clearances per L11; board outline suggestion <= 55x35mm (target, non-binding).
+- bom.csv / pos.csv -- per L1; pos.csv includes rotation column (feeds L11 rot-aware check).
+- reports/ -- gate evidence JSON from tools/gate_runner.py.
+
+## 5. Acceptance gates (deterministic, tools/gate_runner.py evidence only)
+- g-net: parsed sch netlist == section 1 set exactly; net count == 6.
+- g-l10: regex scan for 3.3V-name variants in sch+pcb yields zero hits outside "+3V3".
+- g-l11: pad-pitch/courtyard matrix min gap >= 0.25mm; 0402 pad geom 1.0x0.5 present; U1 side-pad row pitch >= 1.5mm.
+- g-l16: every net pin has wire+label; zero label-less pin wires.
+- g-pos: set(bom.refs) == set(pos.refs), len == 10.
+- g-grid: all placement origins on 0.5mm grid.
+Fail on any gate -> revert to last checkpoint; 3 design-fails on same gate -> ESCALATE with options menu.
+
+## 6. Out of scope
+Antenna keepout tuning, ESD parts, USB data lines, battery/charge, strapping-button circuits, any board outside fixtures/.

package/graders/pcb-agent/seed/spec.json

@@ -0,0 +1,129 @@
+{
+ "schema_version": "1.0",
+ "board": {
+  "name": "toy-m2",
+  "_provenance": "TOY-FIXTURE netlist from esp32s3-r12-BRIEF.txt + architect corrections (7 nets/9 refs). U1 pin-pad function mapping = FIXTURE CONVENTION (toy GPIOs on pads 4/5/9), NOT silicon pinout \u2014 HUMAN VERIFICATION REQUIRED before any real-order use. | C1/C2 0603 deviation per pad-corridor DRC class",
+  "project": "board-lab toy M2 full-cycle"
+ },
+ "components": [
+  {
+   "ref": "U1",
+   "mpn": "ESP32-S3-WROOM-1-N8R8",
+   "footprint": "RF_Module:ESP32-S3-WROOM-1",
+   "pins": {
+    "1": "GND",
+    "2": "+3V3",
+    "3": "+3V3",
+    "4": "GPIO4",
+    "5": "GPIO5",
+    "9": "GPIO2",
+    "21": "GND",
+    "6": "NC(pin unused)",
+    "7": "NC(pin unused)",
+    "8": "NC(pin unused)",
+    "10": "NC(pin unused)",
+    "11": "NC(pin unused)",
+    "12": "NC(pin unused)",
+    "13": "NC(pin unused)",
+    "14": "NC(pin unused)",
+    "15": "NC(pin unused)",
+    "16": "NC(pin unused)",
+    "17": "NC(pin unused)",
+    "18": "NC(pin unused)",
+    "19": "NC(pin unused)",
+    "20": "NC(pin unused)"
+   }
+  },
+  {
+   "ref": "U2",
+   "mpn": "ME6211C33",
+   "footprint": "Package_TO_SOT_SMD:SOT-23",
+   "pins": {
+    "1": "+5V_IN",
+    "2": "GND",
+    "3": "+3V3"
+   }
+  },
+  {
+   "ref": "J1",
+   "mpn": "USB4110",
+   "footprint": "Connector_USB:USB_C_Receptacle_GCT_USB4110",
+   "pins": {
+    "1": "GND",
+    "2": "NC(pin unused)",
+    "3": "NC(pin unused)",
+    "4": "+5V_IN",
+    "5": "NC(pin unused)",
+    "6": "+5V_IN",
+    "7": "NC(pin unused)",
+    "8": "GND",
+    "9": "GND",
+    "10": "NC(pin unused)",
+    "11": "NC(pin unused)",
+    "12": "NC(pin unused)",
+    "13": "NC(pin unused)",
+    "14": "NC(pin unused)",
+    "15": "NC(pin unused)",
+    "16": "GND"
+   }
+  },
+  {
+   "ref": "H1",
+   "mpn": "HDR1x4",
+   "footprint": "Connector_PinHeader_2.54mm:PinHeader_1x04_P2.54mm_Vertical",
+   "pins": {
+    "1": "+3V3",
+    "2": "GPIO4",
+    "3": "GPIO5",
+    "4": "GND"
+   }
+  },
+  {
+   "ref": "C1",
+   "mpn": "100nF",
+   "footprint": "Capacitor_SMD:C_0603_1608Metric",
+   "pins": {
+    "1": "+3V3",
+    "2": "GND"
+   },
+   "_dev": "0402->0603: pad-pair corridor (0.36mm) admits no 0.2mm track w/ 0.2 clr; fixture deviation logged"
+  },
+  {
+   "ref": "C2",
+   "mpn": "100nF",
+   "footprint": "Capacitor_SMD:C_0603_1608Metric",
+   "pins": {
+    "1": "+3V3",
+    "2": "GND"
+   },
+   "_dev": "0402->0603: pad-pair corridor (0.36mm) admits no 0.2mm track w/ 0.2 clr; fixture deviation logged"
+  },
+  {
+   "ref": "C3",
+   "mpn": "10uF",
+   "footprint": "Capacitor_SMD:C_0603_1608Metric",
+   "pins": {
+    "1": "+3V3",
+    "2": "GND"
+   }
+  },
+  {
+   "ref": "D1",
+   "mpn": "LED",
+   "footprint": "LED_SMD:LED_0603_1608Metric",
+   "pins": {
+    "1": "+3V3",
+    "2": "LED1"
+   }
+  },
+  {
+   "ref": "R1",
+   "mpn": "1k",
+   "footprint": "Resistor_SMD:R_0603_1608Metric",
+   "pins": {
+    "1": "LED1",
+    "2": "GPIO2"
+   }
+  }
+ ]
+}