@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/skills/galdr-ymirsystem/scripts/compliance-check.sh

@@ -0,0 +1,360 @@
+#!/usr/bin/env bash
+# compliance-check.sh — Galdr/Tyr compliance gates for the Ymir runtime + skills.
+#
+# Runs the runtime acceptance gates as one command, TOON output on stdout,
+# structured errors, no prompts, idempotent, --version fast path.
+#
+# Usage:
+#   compliance-check.sh [--json] [--quiet]
+#   compliance-check.sh --version | -v
+#
+# Gates:
+#   toon      TOON blocks in galdr SKILL.md + assets + tyr SKILL.md + AGENTS.md
+#   naming    no imported terms (captain/crewmate; firstmate only in provenance)
+#   mocks     no mock/stub/placeholder in the shipped runtime (bin/*.sh)
+#   syntax    bash -n on bin/*.sh; node --check on plugins
+#   json      every runtime JSON parses
+#   sync      galdr-ymirsystem/assets mirrors tyr-check/assets
+#   surfaces  Galdr agent+skill dual-surface
+#   harnesses every harness agent dir resolves into .agents/agents (Rule 02);
+#             no nested SKILL.md carried as a phantom skill
+#   skillindex every real skill is indexed in .agents/skills/README.md, and every
+#             .agents/skills/<name> path cited by the assets resolves
+#   assets    a governed path changed without its owning asset
+#   duplicates no duplicate asset trees
+#   governed  every governed path exists
+#
+# Exit: 0 = all pass, 1 = one or more FAIL, 2 = usage error.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+GALDR="$ROOT/.agents/skills/galdr-ymirsystem"
+TYR="$ROOT/.agents/skills/tyr-check"
+TOON_CHECK="$SCRIPT_DIR/toon-check.py"
+
+for a in "$@"; do
+  case "$a" in
+    -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+    -h|--help) sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  esac
+done
+
+QUIET=0
+JSON=0
+for a in "$@"; do
+  [ "$a" = "--quiet" ] && QUIET=1
+  [ "$a" = "--json" ] && JSON=1
+done
+
+declare -a IDS CHECKS STATUS DETAILS
+add() { IDS+=("$1"); CHECKS+=("$2"); STATUS+=("$3"); DETAILS+=("$4"); }
+
+say() { [ "$QUIET" = 1 ] || printf '%s\n' "$1"; }
+
+# --- toon -------------------------------------------------------------------
+toon_targets=("$GALDR/SKILL.md")
+[ -d "$GALDR/assets" ] && toon_targets+=("$GALDR/assets")
+[ -f "$TYR/SKILL.md" ] && toon_targets+=("$TYR/SKILL.md")
+[ -f "$ROOT/AGENTS.md" ] && toon_targets+=("$ROOT/AGENTS.md")
+if out=$(python3 "$TOON_CHECK" "${toon_targets[@]}" 2>&1); then
+  nblocks=$(printf "%s" "$out" | grep -c '^  "' || true)
+  add toon "TOON blocks valid" PASS "${nblocks} blocks valid"
+else
+  add toon "TOON blocks valid" FAIL "$(printf '%s' "$out" | grep -m1 '^error:' || echo 'violations')"
+fi
+
+# --- naming -----------------------------------------------------------------
+# Scope: the always-loaded contract and the shipped runtime. Law statements that
+# name a forbidden term ("never captain", "no imported term") are not violations.
+naming_fail=""
+for f in "$ROOT/AGENTS.md" "$ROOT"/bin/*.sh; do
+  [ -f "$f" ] || continue
+  # The Huginn observer is the read-only bridge to the external distro; it
+  # legitimately names that system's tooling and paths.
+  [ "${f##*/}" = "nornir-job-observer.sh" ] && continue
+  hit=$(grep -nEi 'captain|crewmate' "$f" 2>/dev/null | grep -vEi 'never|imported|\.treehouse' || true)
+  [ -n "$hit" ] && naming_fail="$naming_fail ${f##*/}:$(printf '%s' "$hit" | head -n1 | cut -d: -f1)"
+done
+# Note: the upstream project name is permitted in the assets as provenance
+# (paths, env bindings, and the port record); this gate checks the runtime only.
+if [ -z "$naming_fail" ]; then
+  add naming "no imported terms" PASS "Allfather + Norse names only"
+else
+  add naming "no imported terms" FAIL "imported term at$naming_fail"
+fi
+
+# --- mocks ------------------------------------------------------------------
+# A legitimate filename is not a stub: TODO.md appears in an allowlist in
+# bin/public-guard.sh, so ignore that filename (not the word) here.
+mock_hits=$(grep -rniE '\b(mock|stub|placeholder|todo)\b' "$ROOT/bin" 2>/dev/null | grep -v 'PUBLIC=' || true)
+if [ -z "$mock_hits" ]; then
+  add mocks "no mocks in shipped runtime" PASS "bin/ clean"
+else
+  add mocks "no mocks in shipped runtime" FAIL "$(printf '%s' "$mock_hits" | head -n1)"
+fi
+
+# --- syntax -----------------------------------------------------------------
+syn_fail=""
+for f in "$ROOT"/bin/*.sh; do
+  [ -e "$f" ] || continue
+  bash -n "$f" 2>/dev/null || syn_fail="$syn_fail ${f##*/}"
+done
+while IFS= read -r f; do
+  node --check "$f" 2>/dev/null || syn_fail="$syn_fail $(basename "$f")"
+done < <(find "$ROOT/.opencode/plugins" -name '*.js' 2>/dev/null)
+if [ -z "$syn_fail" ]; then
+  add syntax "shell + plugin syntax" PASS "bash -n + node --check clean"
+else
+  add syntax "shell + plugin syntax" FAIL "failed:$syn_fail"
+fi
+
+# --- json -------------------------------------------------------------------
+json_fail=""
+while IFS= read -r f; do
+  python3 -m json.tool "$f" >/dev/null 2>&1 || json_fail="$json_fail ${f##*/}"
+done < <(find "$ROOT/config" "$ROOT/.claude" "$ROOT/.codex" "$ROOT/.cursor" "$ROOT/.agents/skills/galdr-ymirsystem/assets/pi-boot" "$ROOT/.agents/sandbox" \
+  -maxdepth 1 -name '*.json' 2>/dev/null; [ -f "$ROOT/opencode.json" ] && echo "$ROOT/opencode.json")
+if [ -z "$json_fail" ]; then
+  add json "runtime JSON parses" PASS "all parse"
+else
+  add json "runtime JSON parses" FAIL "failed:$json_fail"
+fi
+
+# --- sync -------------------------------------------------------------------
+if diff -rq "$GALDR/assets" "$TYR/assets" >/dev/null 2>&1; then
+  add sync "galdr/tyr assets mirrored" PASS "in sync"
+else
+  add sync "galdr/tyr assets mirrored" FAIL "drift detected"
+fi
+
+# --- surfaces ---------------------------------------------------------------
+# Galdr is dual-surface: the agent must resolve to the canonical skill.
+if [ -L "$ROOT/.agents/agents/galdr.md" ] && [ "$(readlink "$ROOT/.agents/agents/galdr.md")" = "../skills/galdr-ymirsystem/SKILL.md" ]; then
+  add surfaces "Galdr agent+skill dual-surface" PASS "agent symlinks the skill"
+elif diff -q "$ROOT/.agents/agents/galdr.md" "$GALDR/SKILL.md" >/dev/null 2>&1; then
+  add surfaces "Galdr agent+skill dual-surface" PASS "agent mirrors the skill"
+else
+  add surfaces "Galdr agent+skill dual-surface" FAIL "agent and skill differ"
+fi
+
+# --- harnesses --------------------------------------------------------------
+# Every harness reads agents through its own directory (.claude/agents,
+# .codex/agents, .cursor/agents, .pi/agents, .opencode/agent) and skills through
+# .agents/skills. Two failure classes hide there, and neither is visible from
+# the code: a symlink that no longer resolves (Rule 02 — .agents/agents is
+# canonical, harness dirs are symlinks), and a nested SKILL.md that a recursive
+# scanner loads as a second, phantom skill. Both have bitten this tree: the
+# galdr-cli rename left .agents/agents/galdr.md dangling for days, and three
+# superseded SKILL.md files were being loaded as live skills.
+harness_problems=""; harness_links=0
+for hd in .claude/agents .codex/agents .cursor/agents .pi/agents .opencode/agent; do
+  [ -d "$ROOT/$hd" ] || continue
+  for entry in "$ROOT/$hd"/*; do
+    [ -e "$entry" ] || [ -L "$entry" ] || continue
+    if [ ! -L "$entry" ]; then
+      harness_problems="$harness_problems ${hd}/$(basename "$entry")(real-file-not-symlink)"
+    elif [ ! -e "$entry" ]; then
+      harness_problems="$harness_problems ${hd}/$(basename "$entry")(dangling)"
+    else
+      harness_links=$((harness_links+1))
+      # One hop only: the link must land in the canonical tree. It may then be a
+      # symlink onward (Galdr's agent IS the skill, by design) — following the
+      # whole chain here would wrongly call that off-tree. normpath is textual,
+      # so the final symlink is deliberately left unresolved.
+      hop_target="$(readlink "$entry")"
+      case "$hop_target" in
+        /*) hop_abs="$hop_target" ;;
+        *)  hop_abs="$(dirname "$entry")/$hop_target" ;;
+      esac
+      hop="$(python3 -c 'import os,sys; print(os.path.normpath(sys.argv[1]))' "$hop_abs" 2>/dev/null || printf '%s' "$hop_abs")"
+      case "$hop" in
+        "$ROOT/.agents/agents/"*) : ;;
+        *) harness_problems="$harness_problems ${hd}/$(basename "$entry")(off-canonical-tree)" ;;
+      esac
+    fi
+  done
+done
+# A nested SKILL.md that carries YAML frontmatter is loaded by every recursive
+# scanner as a phantom skill. A nested SKILL.md WITHOUT frontmatter is an inert
+# template (the NSR scaffolding layer) and is left alone.
+phantom=""
+while IFS= read -r sk; do
+  [ -n "$sk" ] || continue
+  rel="${sk#"$ROOT"/}"
+  [ "$(printf '%s' "$rel" | awk -F/ '{print NF}')" -gt 4 ] || continue
+  [ "$(head -1 "$sk")" = "---" ] && phantom="$phantom ${rel#.agents/skills/}"
+done < <(find "$ROOT/.agents/skills" -name SKILL.md 2>/dev/null | sort)
+# The ONE skills tree (`.agents/skills`) must reach EVERY harness, each by its
+# own mechanism — and a harness silently loading nothing is invisible from the
+# code, so it is asserted here:
+#   opencode  — `skills.paths: [".agents/skills"]` in the tracked example
+#   pi        — native discovery: it walks up from the cwd to `.agents/skills`
+#               (and `~/.agents/skills`), so it needs no link and no config
+#   claude · codex · cursor — project scope is their own dir: each gets
+#               `<harness>/skills -> ../.agents/skills`
+skills_gaps=""
+grep -q '\.agents/skills' "$ROOT/opencode.json.example" 2>/dev/null \
+  || skills_gaps="$skills_gaps opencode(skills.paths missing from opencode.json.example)"
+[ -d "$ROOT/.agents/skills" ] || skills_gaps="$skills_gaps .agents/skills(missing tree)"
+for hd in .claude .codex .cursor; do
+  [ -d "$ROOT/$hd" ] || continue
+  if [ ! -L "$ROOT/$hd/skills" ]; then
+    skills_gaps="$skills_gaps ${hd}/skills(absent)"
+  else
+    case "$(readlink "$ROOT/$hd/skills")" in
+      ../.agents/skills) : ;;
+      *) skills_gaps="$skills_gaps ${hd}/skills(wrong target)" ;;
+    esac
+  fi
+done
+
+harness_detail=""
+[ -n "$harness_problems" ] && harness_detail="broken agent links:$harness_problems"
+[ -n "$phantom" ] && harness_detail="$harness_detail phantom skills:$phantom"
+[ -n "$skills_gaps" ] && harness_detail="$harness_detail skills not bound:$skills_gaps"
+if [ -z "$harness_detail" ]; then
+  add harnesses "harness surfaces + skill discovery" PASS "$harness_links agent links resolve; skills bound (opencode config · pi native · claude/codex/cursor linked); no phantom skills"
+else
+  add harnesses "harness surfaces + skill discovery" FAIL "$harness_detail"
+fi
+
+# --- skillindex -------------------------------------------------------------
+# The canonical index is .agents/skills/README.md. Every real skill must be named
+# there, and every skill path the Galdr assets cite must resolve. This is the
+# check that would have caught the drift by hand: three superseded skills stayed
+# "live" in the registry long after their files were gone, and the registry table
+# pointed at a whole layout (smidja/, gunnlod, hamr, saga, ymir, open-design)
+# that no longer existed. A line marked planned/legacy/superseded is exempt by
+# intent — an index may name what is coming or gone, but not what never was.
+real_skills="$(find -L "$ROOT/.agents/skills" -mindepth 2 -maxdepth 2 -name SKILL.md -printf '%h\n' 2>/dev/null | while read -r d; do basename "$d"; done | sort)"
+indexed="$(grep -oE '^  "[A-Za-z0-9._-]+"' "$ROOT/.agents/skills/README.md" 2>/dev/null | tr -d ' "' | sort -u)"
+missing_index="$(comm -23 <(printf '%s\n' "$real_skills") <(printf '%s\n' "$indexed") | tr '\n' ' ')"
+extra_index="$(comm -13 <(printf '%s\n' "$real_skills") <(printf '%s\n' "$indexed") | tr '\n' ' ')"
+dead_refs=""
+while IFS= read -r line; do
+  case "$line" in
+    *planned*|*Planned*|*legacy*|*Legacy*|*superseded*|*Superseded*|*removed*|*Removed*|*abandoned*|*retired*|*former*) continue ;;
+  esac
+  for ref in $(printf '%s' "$line" | grep -oE '\.agents/skills/[A-Za-z0-9._-]+' | sort -u); do
+    case "$ref" in *.md) continue ;; esac   # a file in the tree, not a skill dir
+    [ -d "$ROOT/$ref" ] || dead_refs="$dead_refs $ref"
+  done
+done < <(cat "$GALDR"/assets/*.md "$ROOT/.agents/agents/brokk.md" 2>/dev/null)
+skill_detail=""
+[ -n "$(printf '%s' "$missing_index" | tr -d ' ')" ] && skill_detail="unindexed skills:$missing_index"
+[ -n "$(printf '%s' "$extra_index" | tr -d ' ')" ] && skill_detail="$skill_detail indexed-but-absent:$extra_index"
+[ -n "$(printf '%s' "$dead_refs" | tr -d ' ')" ] && skill_detail="$skill_detail dead skill paths:$dead_refs"
+if [ -z "$skill_detail" ]; then
+  add skillindex "skill index + cited skill paths" PASS "$(printf '%s\n' "$real_skills" | grep -c .) skills, all indexed and cited paths resolve"
+else
+  add skillindex "skill index + cited skill paths" FAIL "$skill_detail"
+fi
+
+# --- assets (governed paths) -------------------------------------------------
+# A governed file changed in the working tree must have its owning asset changed
+# in the same change, or the runtime has drifted from its documentation.
+asset_for() {
+  case "$1" in
+    *bin/ymir-install.sh)                      printf '%s' "$GALDR/assets/installation.md" ;;
+    *apps/hlidskjalf/*)                        printf '%s' "$GALDR/assets/hlidskjalf-ui.md" ;;
+    *bin/mimir*)                               printf '%s' "$GALDR/assets/memory-well.md" ;;
+    *bin/gleipnir-lock-lib.sh|*bin/saga-session-start.sh|*state/.lock) printf '%s' "$GALDR/assets/brokk-distro-runtime.md" ;;
+    *bin/nornir-*|*config/cron.yaml)           printf '%s' "$GALDR/assets/nornir-jobs.md" ;;
+    *bin/valknut-load.sh|*/.pi/*|*/.opencode/*) printf '%s' "$GALDR/assets/harness-integration/README.md" ;;
+    *bin/smidja*|*.agents/skills/smidja-factory/*) printf '%s' "$GALDR/assets/smidja.md" ;;
+    *)                                         printf '' ;;
+  esac
+}
+if command -v git >/dev/null 2>&1 && git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  changed="$(git -C "$ROOT" diff --name-only HEAD 2>/dev/null || true)"
+  stale=""
+  for f in $changed; do
+    a="$(asset_for "/$f")"
+    [ -n "$a" ] || continue
+    # Stale only when the asset itself did NOT also change.
+    printf '%s\n' "$changed" | grep -qxF "${a#"$ROOT"/}" && continue
+    stale="$stale ${f##*/}"
+  done
+  if [ -z "$stale" ]; then
+    add assets "governed assets current" PASS "no stale governed paths"
+  else
+    add assets "governed assets current" FAIL "stale (asset not updated):$stale"
+  fi
+else
+  add assets "governed assets current" SKIP "not a git work tree"
+fi
+
+# --- duplicates -------------------------------------------------------------
+if [ -d "$ROOT/assets/skills/assets" ]; then
+  add duplicates "no duplicate asset trees" FAIL "assets/skills/assets exists"
+else
+  add duplicates "no duplicate asset trees" PASS "single canonical tree"
+fi
+
+# --- governed paths exist ---------------------------------------------------
+# A governed path that does not exist is worse than a missing rule: the pretool
+# guard stops matching silently, so the protection is gone and nothing fails.
+# (A rename left `smidja-factory-factory` in AGENTS.md and in the guard's own
+# pattern, which disabled the smidja rule without a single error.)
+gov_missing=""
+gov_count=0
+while IFS= read -r spec; do
+  [ -n "$spec" ] || continue
+  old_ifs="$IFS"; IFS='|'
+  for alt in $spec; do
+    alt="$(printf '%s' "$alt" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
+    [ -n "$alt" ] || continue
+    gov_count=$((gov_count + 1))
+    [ -e "$ROOT/$alt" ] && continue
+    case "$alt" in
+      *'*'*|*'?'*|*'['*)
+        compgen -G "$ROOT/$alt" >/dev/null 2>&1 || gov_missing="$gov_missing $alt" ;;
+      *)
+        gov_missing="$gov_missing $alt" ;;
+    esac
+  done
+  IFS="$old_ifs"
+done <<EOF
+$(awk '/^governed\[/{f=1;next} f&&/^```/{exit} f{print}' "$ROOT/AGENTS.md" 2>/dev/null | sed -E 's/^ *"([^"]*)".*/\1/')
+EOF
+if [ "$gov_count" = 0 ]; then
+  add governed "governed paths resolve" SKIP "no governed table found in AGENTS.md"
+elif [ -z "$gov_missing" ]; then
+  add governed "governed paths resolve" PASS "all $gov_count governed paths exist"
+else
+  add governed "governed paths resolve" FAIL "missing:$gov_missing"
+fi
+
+# --- output -----------------------------------------------------------------
+if [ "$JSON" = 1 ]; then
+  printf '{\n  "checks": [\n'
+  first=1
+  for i in "${!IDS[@]}"; do
+    [ $first = 0 ] && printf ',\n'
+    first=0
+    printf '    {"id":"%s","check":"%s","status":"%s","detail":"%s"}' \
+      "${IDS[$i]}" "${CHECKS[$i]}" "${STATUS[$i]}" "${DETAILS[$i]}"
+  done
+  printf '\n  ]\n}\n'
+else
+  say "checks[${#IDS[@]}]{id,check,status,detail}:"
+  for i in "${!IDS[@]}"; do
+    say "  \"${IDS[$i]}\",\"${CHECKS[$i]}\",\"${STATUS[$i]}\",\"${DETAILS[$i]}\""
+  done
+fi
+
+fails=0
+for s in "${STATUS[@]}"; do [ "$s" = FAIL ] && fails=$((fails + 1)); done
+if [ "$fails" -gt 0 ]; then
+  if [ "$JSON" = 1 ] || [ "$QUIET" = 1 ]; then
+    printf 'error: %s gate(s) failed\n' "$fails" >&2
+    printf 'help: fix the FAIL rows; see assets/runtime-compliance.md\n' >&2
+  else
+    printf '\nerror: %s gate(s) failed\n' "$fails"
+    printf 'help: fix the FAIL rows above; see assets/runtime-compliance.md\n'
+  fi
+  exit 1
+fi
+exit 0

package/.agents/skills/galdr-ymirsystem/scripts/gpu-sample.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# gpu-sample.sh — sample GPU utilization + VRAM every N seconds while a test runs.
+#
+# Purpose (skill rule #6): catches CPU-spill / partial-GPU behavior that a single
+# post-run number hides. During prefill you want to see 95-100% GPU util; if you
+# see it drop to ~30% while decode continues, experts/KV are offloading to CPU.
+#
+# Usage:
+#   gpu-sample.sh [interval] [count]            # just samples
+#   gpu-sample.sh 2 10 -- curl -s <url> ...     # samples WHILE a command runs
+#
+# Examples:
+#   gpu-sample.sh 2 8
+#   gpu-sample.sh 1 15 -- curl -s http://localhost:8125/v1/chat/completions -d @req.json -o out.json
+set -uo pipefail
+
+INTERVAL=${1:-2}; shift 2>/dev/null || true
+COUNT=${1:-10}; shift 2>/dev/null || true
+
+# remaining args (after optional interval/count) are a command to run while sampling
+if [ "${1:-}" = "--" ]; then
+  shift
+  RUNCMD=("$@")
+  echo "sampling GPU every ${INTERVAL}s × ${COUNT} while running: $*"
+  ( for i in $(seq 1 "$COUNT"); do
+      nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader | sed "s/^/t+${INTERVAL}s  /"
+      sleep "$INTERVAL"
+    done ) &
+  SAMPLER=$!
+  "${RUNCMD[@]}"
+  RC=$?
+  wait "$SAMPLER" || true
+  exit $RC
+fi
+
+# plain sampling (no command)
+echo "sampling GPU every ${INTERVAL}s × ${COUNT}"
+for i in $(seq 1 "$COUNT"); do
+  nvidia-smi --query-gpu=utilization.gpu,memory.used,clocks.sm --format=csv,noheader | sed "s/^/t+${INTERVAL}s  /"
+  sleep "$INTERVAL"
+done
+echo "done"
+echo "NOTE: util≈95-100% during prefill = good; util ~30% while decoding = CPU spill."

package/.agents/skills/galdr-ymirsystem/scripts/stop-all.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# stop-all.sh — clear anything a bench left behind, and report what holds the GPU.
+#
+# It stops ONLY the throwaway servers this skill started (they live on scratch
+# ports in the 9200-9999 range) and then tells you the truth about the device,
+# without pretending to manage anyone else's service.
+#
+# Usage: stop-all.sh
+set -uo pipefail
+
+echo "=== throwaway bench servers ==="
+found=0
+if command -v pgrep >/dev/null 2>&1; then
+  for p in $(pgrep -f "llama-server .*--port 9[2-9][0-9][0-9]" 2>/dev/null || true); do
+    kill "$p" 2>/dev/null && { echo "  asked pid $p to stop"; found=1; }
+  done
+fi
+[ "$found" = "0" ] && echo "  none running"
+
+sleep 1
+echo
+echo "=== GPU ==="
+if command -v nvidia-smi >/dev/null 2>&1; then
+  nvidia-smi --query-compute-apps=pid,process_name,used_memory --format=csv 2>/dev/null | sed 's/^/  /'
+  echo
+  nvidia-smi --query-gpu=memory.used,memory.total,utilization.gpu --format=csv,noheader | sed 's/^/  used/total/util: /'
+  echo "  (a clean test baseline is the device's idle floor — a few MiB, or more on a desktop)"
+elif command -v rocm-smi >/dev/null 2>&1; then
+  rocm-smi --showmemuse 2>/dev/null | sed 's/^/  /'
+else
+  echo "  no nvidia-smi or rocm-smi here."
+  echo "  Find the holder yourself (lsof / ps) — and note that a model resident in"
+  echo "  another service will contaminate your next measurement."
+fi

package/.agents/skills/galdr-ymirsystem/scripts/toon-check.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""toon-check — validate Token-Oriented Object Notation (TOON) blocks.
+
+Galdr-style CLI: TOON output on stdout, structured errors, no prompts, --version
+fast path, definitive empty states.
+
+Usage:
+  toon-check.py [paths...] [--quiet] [--json]
+  toon-check.py --version | -v
+
+For every TOON table block  TYPE[COUNT]{F1,F2,...}:  this checks that
+  - exactly COUNT data rows follow (2-space or tab indented, before a blank line), and
+  - every row has exactly len(F1,F2,...) comma-separated fields (quotes respected).
+
+Exit: 0 = clean, 1 = violations, 2 = usage error.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+
+VERSION = "1.0.0"
+HEADER = re.compile(r"^(?P<indent>[ \t]*)(?P<name>[A-Za-z_][\w-]*)\[(?P<count>\d+)\]\{(?P<fields>[^}]*)\}:[ \t]*$")
+ROW = re.compile(r"^(?P<indent>[ \t]+)(?P<body>\S.*?)[ \t]*$")
+
+
+def split_fields(row: str) -> list[str]:
+    """Split a TOON/CSV row on commas that are not inside double quotes."""
+    fields: list[str] = []
+    cur = ""
+    in_quotes = False
+    i = 0
+    while i < len(row):
+        ch = row[i]
+        if ch == '"':
+            if in_quotes and i + 1 < len(row) and row[i + 1] == '"':
+                cur += '"'
+                i += 2
+                continue
+            in_quotes = not in_quotes
+            cur += ch
+        elif ch == "," and not in_quotes:
+            fields.append(cur.strip())
+            cur = ""
+        else:
+            cur += ch
+        i += 1
+    fields.append(cur.strip())
+    return fields
+
+
+def scan_file(path: str) -> list[dict]:
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            lines = fh.read().splitlines()
+    except OSError:
+        return []
+
+    blocks: list[dict] = []
+    i = 0
+    while i < len(lines):
+        m = HEADER.match(lines[i])
+        if not m:
+            i += 1
+            continue
+        declared = int(m.group("count"))
+        expected = [f.strip() for f in m.group("fields").split(",") if f.strip() != ""]
+        rows: list[list[str]] = []
+        elided = False
+        j = i + 1
+        while j < len(lines):
+            raw = lines[j]
+            if raw.strip() == "":
+                break
+            rm = ROW.match(raw)
+            if not rm:
+                break
+            body = rm.group("body")
+            if body.strip() == "...":
+                elided = True
+                j += 1
+                continue
+            rows.append(split_fields(body))
+            j += 1
+        blocks.append(
+            {
+                "file": path,
+                "type": m.group("name"),
+                "declared": declared,
+                "actual": len(rows),
+                "cols": len(expected),
+                "row_cols": sorted({len(r) for r in rows}),
+                "line": i + 1,
+                "elided": elided,
+            }
+        )
+        i = j
+    return blocks
+
+
+def status(block: dict) -> str:
+    if block.get("elided"):
+        return "ELIDED"
+    if block["actual"] != block["declared"]:
+        return "COUNT_MISMATCH"
+    bad = [c for c in block["row_cols"] if c != block["cols"]]
+    if bad:
+        return "COLS_MISMATCH"
+    return "PASS"
+
+
+def emit(rows: list[dict], quiet: bool, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(rows, indent=2))
+        return
+    if not rows:
+        print("toon_blocks: 0 TOON blocks found")
+        return
+    if not quiet:
+        print(f"toon_blocks[{len(rows)}]{{file,type,line,declared,actual,cols,status}}:")
+        for r in rows:
+            print(
+                f'  "{r["file"]}",{r["type"]},{r["line"]},{r["declared"]},'
+                f'{r["actual"]},{r["cols"]},"{r["status"]}"'
+            )
+
+
+def main(argv: list[str]) -> int:
+    if any(a in ("-v", "-V", "--version") for a in argv):
+        print(VERSION)
+        return 0
+    if any(a in ("-h", "--help") for a in argv):
+        print(__doc__.strip())
+        return 0
+
+    quiet = "--quiet" in argv
+    as_json = "--json" in argv
+    paths = [a for a in argv if not a.startswith("-")]
+    if not paths:
+        print("error: no paths given")
+        print("help: toon-check.py <file-or-dir> [...] [--quiet] [--json]")
+        return 2
+    for p in paths:
+        if not os.path.exists(p):
+            print(f"error: path not found: {p}")
+            print("help: pass a Markdown file or a directory to scan")
+            return 2
+
+    files: list[str] = []
+    for p in paths:
+        if os.path.isdir(p):
+            for root, _dirs, names in os.walk(p):
+                for n in names:
+                    if n.endswith(".md"):
+                        files.append(os.path.join(root, n))
+        else:
+            files.append(p)
+
+    rows: list[dict] = []
+    for f in sorted(files):
+        rows.extend(scan_file(f))
+    for r in rows:
+        r["status"] = status(r)
+
+    emit(rows, quiet, as_json)
+    bad = [r for r in rows if r["status"] not in ("PASS", "ELIDED")]
+    if bad:
+        print("")
+        for r in bad:
+            if r["status"] == "COUNT_MISMATCH":
+                print(
+                    f'error: {r["file"]}:{r["line"]} {r["type"]}[{r["declared"]}] '
+                    f'declares {r["declared"]} rows but has {r["actual"]}'
+                )
+            else:
+                print(
+                    f'error: {r["file"]}:{r["line"]} {r["type"]} rows have '
+                    f'{r["row_cols"]} fields, header has {r["cols"]}'
+                )
+        print("help: fix the TOON block header count/fields to match the rows")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/.agents/skills/gjallarhorn-relay/README.md

@@ -0,0 +1,3 @@
+# gjallarhorn-relay — relay — public replies (X/Discord)
+
+See `SKILL.md` for the full skill.