From ca687b660912c7e441e24b0f7d767b2f3b63a1db Mon Sep 17 00:00:00 2001 From: shinyobjectz Date: Mon, 9 Nov 2026 06:03:17 -0800 Subject: [PATCH] skills: the craft guides travel with the raea skill (raea-skills 4db36f6), and tools/skills.sh coverage says what nothing teaches tools/skills.sh gen copies sdk/guides/craft into the skill by one list (copies()): bevy/ as 3d/ as before, and now motion.md and motion/, and the router, floor, rubric, modes/ and verbs/ under craft/, each folder with its NOTICE. check fails on a copy that differs from its guide and on a copy whose guide is gone, in any of those folders (3d/plugins.md and 3d/rows.md are the skill's own). tools/skills.sh coverage lists every verb in raea's help, every SDK entry (sdk/raea/src) and every feed tool with whether a guide or the skill teaches it outside reference/; check warns on each untaught one, so new engine surface shows in L1. COVERAGE_SKIP holds what an agent never runs (hook, traces, raea/dev_tools, raea/test), each with why. On this main with raea-skills 4db36f6: 43 of 43 verbs, 28 of 28 SDK entries, 19 of 19 feed tools. Mutants checked: an edited copy and an orphaned copy fail, an untaught verb warns. --- skills | 2 +- tools/skills.sh | 92 ++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 76 insertions(+), 18 deletions(-) diff --git a/skills b/skills index bc52595f..4db36f63 160000 --- a/skills +++ b/skills @@ -1 +1 @@ -Subproject commit bc52595f6d1d048eba8b1c8df221a6bd927cd050 +Subproject commit 4db36f63504273595cfcea4a14a2895b04465fc3 diff --git a/tools/skills.sh b/tools/skills.sh index 6a2a2fe0..5cbf0229 100755 --- a/tools/skills.sh +++ b/tools/skills.sh @@ -4,9 +4,10 @@ # links these instead of repeating them, so a verb, a flag, a feed tool or an export changes its reference in the # same commit. # -# tools/skills.sh gen write skills/skills/raea/reference/{cli,feed,files,sdk,app}.md, and copy the Bevy craft guides -# (sdk/guides/craft/bevy/*.md) into skills/skills/raea/3d/ as its 3D topic files, so a clone of -# raea-skills reads whole without raea; commit both in raea-skills, then the pointer here +# tools/skills.sh gen write skills/skills/raea/reference/{cli,feed,files,sdk,app}.md, and copy the craft guides +# (sdk/guides/craft, what `raea guide` prints) into the skill (copies() below: bevy/ as 3d/, +# motion.md and motion/, and the router, floor, rubric, modes/ and verbs/ under craft/), so a +# clone of raea-skills reads whole without raea; commit them in raea-skills, then the pointer here # tools/skills.sh check the drift gate (SK3, in L0): fails on a stale reference, a retired word, a flag a verb # doesn't take, a RAEA_* variable nothing reads, or a relative link that goes nowhere, each # with its file, line and fix. engine/cli/conformance/surface.test.ts checks the verbs and @@ -19,6 +20,8 @@ # build of this tree, so its help is the truth and every difference fails. # tools/skills.sh check-cli cli.md against RAEA_BIN's help alone, with no feed app: tools/release.sh on a public # checkout, where RAEA_BIN is the release's own build +# tools/skills.sh coverage each verb, SDK entry and feed tool, and how many a guide or the skill teaches (coverage() below); +# check warns on each one untaught # tools/skills.sh stale every section with sources, by how many commits to them it has missed since it last changed # # Sources: cli.md from `raea help --json` (engine/cli/src/usage.rs); feed.md from FEED_TOOLS (apps/app @@ -33,7 +36,23 @@ ROOT=$(cd "$(dirname "$0")/.." && pwd) cd "$ROOT" SK=skills/skills OUT=${SKILLS_OUT:-$SK/raea/reference} -BEVY_OUT=${SKILLS_BEVY_OUT:-$SK/raea/3d} +# where gen-into puts the copied guides (copies() names them relative to it): the skill itself, or a scratch folder +COPY_OUT=${SKILLS_COPY_OUT:-$SK/raea} +# the guides the skill carries, each as SOURCECOPY (COPY relative to the skill): `raea guide NAME` prints the source, +# and the skill's routers (3d.md, and one per domain in raea-skills) link the copy. Skill-only files beside the copies +# (3d/plugins.md, 3d/rows.md) aren't listed. +copies() { + local g + for g in sdk/guides/craft/bevy/*.md sdk/guides/craft/bevy/NOTICE; do printf '%s\t3d/%s\n' "$g" "${g##*/}"; done + printf '%s\tmotion.md\n' sdk/guides/craft/motion.md + for g in sdk/guides/craft/motion/*.md; do printf '%s\tmotion/%s\n' "$g" "${g##*/}"; done + for g in ROUTER.md floor.md rubric.md NOTICE; do printf '%s\tcraft/%s\n' "sdk/guides/craft/$g" "$g"; done + for g in sdk/guides/craft/modes/*.md; do printf '%s\tcraft/modes/%s\n' "$g" "${g##*/}"; done + for g in sdk/guides/craft/verbs/*.md; do printf '%s\tcraft/verbs/%s\n' "$g" "${g##*/}"; done +} +# the folders whose every file is a copy (a file there with no source is one whose guide was removed or renamed) +COPY_DIRS="3d motion craft craft/modes craft/verbs" +SKILL_ONLY="3d/plugins.md 3d/rows.md" HEAD_LINE="" APP=${RAEA_APP:-apps/app} # check-cli reads only raea's help, so it runs where the feed app isn't (a public checkout: release.yml's runners) @@ -205,6 +224,34 @@ help_stale() { [ -n "$newest" ] && [ "$built" -lt "$newest" ] } +# Surface coverage (raea-skills docs/TREE.md): each verb in raea's help, each SDK entry (sdk/raea/src) and each feed tool, +# with whether a guide or the skill teaches it outside the generated reference (texts(): sdk/guides/craft and the skill's +# own files, not reference/). A row is KINDNAMEtaught|untaught|skip. The reference lists everything; coverage +# asks whether anything says when and how to use it. COVERAGE_SKIP names what an agent never runs, each with why. +COVERAGE_SKIP="verb:hook (raea skills install sets it up; an agent never runs it) +verb:traces (raea's own session logs, for whoever debugs raea) +module:dev_tools (raea's own debugging overlays) +module:test (raea's test harness, for raea's own tests)" +coverage() { + local corpus v m t f; corpus=$(mktemp "${TMPDIR:-/tmp}/skills-cov.XXXXXX") + texts | while read -r f; do cat "$f"; echo; done > "$corpus" + row() { # KIND NAME PATTERN (an extended regex) + if printf '%s\n' "$COVERAGE_SKIP" | grep -q "^$1:$2 "; then printf '%s\t%s\tskip\n' "$1" "$2" + elif grep -qE "$3" "$corpus"; then printf '%s\t%s\ttaught\n' "$1" "$2" + else printf '%s\t%s\tuntaught\n' "$1" "$2"; fi + } + if [ "${stale_help:-0}" != 1 ]; then + for v in $("$R" help --json | jq -r '.verbs[].verb' | sort -u); do row verb "$v" "raea $v([^a-z_-]|\$)"; done + fi + for f in sdk/raea/src/*.ts sdk/raea/src/*.tsx; do + m=${f##*/}; m=${m%.tsx}; m=${m%.ts} + case $m in index | prelude | pure | native-calls | *.gen) continue ;; esac + row module "$m" "raea/$m([^a-z_-]|\$)" + done + for t in $(gen_feed | sed -n 's/^## //p'); do row tool "$t" "(^|[^a-z_])$t([^a-z_]|\$)"; done + rm -f "$corpus" +} + check() { local fail=0 tmp; tmp=$(mktemp -d "${TMPDIR:-/tmp}/skills-check.XXXXXX") [ -f "$SK/raea/SKILL.md" ] || { echo "FAIL skills: $SK/raea/SKILL.md:1: missing; fix: git submodule update --init skills (raea-skills, at the commit raea pins)"; rm -rf "$tmp"; return 1; } @@ -213,7 +260,7 @@ check() { echo "skills: note $R is older than the help's sources; cli.md and the flags aren't checked (rebuild raea-cli)" fi local stale_help=0; help_stale && stale_help=1 - SKILLS_OUT=$tmp/ref SKILLS_BEVY_OUT=$tmp/bevy R=$R SKIP_CLI=$stale_help "$0" gen-into >/dev/null || { echo "FAIL skills: tools/skills.sh gen failed"; rm -rf "$tmp"; return 1; } + SKILLS_OUT=$tmp/ref SKILLS_COPY_OUT=$tmp/copies R=$R SKIP_CLI=$stale_help "$0" gen-into >/dev/null || { echo "FAIL skills: tools/skills.sh gen failed"; rm -rf "$tmp"; return 1; } for f in cli feed files sdk app; do [ "$f" = cli ] && [ $stale_help = 1 ] && continue if ! diff -q "$tmp/ref/$f.md" "$SK/raea/reference/$f.md" >/dev/null 2>&1; then @@ -234,21 +281,27 @@ check() { fi fi done - # the 3D topic files (raea/3d/): copies of the Bevy craft guides, so raea-skills reads whole on its own (and on GitHub) - local g c - for g in sdk/guides/craft/bevy/*.md; do - c=$SK/raea/3d/${g##*/} - cmp -s "$g" "$c" && continue + # the guides the skill carries (copies()): each a copy of its source, and no copy left whose guide is gone, so raea-skills + # reads whole on its own (and on GitHub) and says what `raea guide` says + local g c d + while IFS=$'\t' read -r g c; do + cmp -s "$g" "$SK/raea/$c" && continue if [ "$(git symbolic-ref -q HEAD 2>/dev/null)" = refs/heads/gitbutler/workspace ]; then - echo "skills: warning $c differs from $g (other lanes' code is applied here; L1's export decides)" + echo "skills: warning $SK/raea/$c differs from $g (other lanes' code is applied here; L1's export decides)" else - echo "FAIL skills: $c:1: isn't a copy of $g; fix: tools/skills.sh gen, and commit it in raea-skills, then the pointer"; fail=1 + echo "FAIL skills: $SK/raea/$c:1: isn't a copy of $g; fix: tools/skills.sh gen, and commit it in raea-skills, then the pointer"; fail=1 fi + done < <(copies) + for d in $COPY_DIRS; do + for c in "$SK/raea/$d"/*; do + [ -f "$c" ] || continue + c=${c#"$SK/raea/"} + case " $SKILL_ONLY " in *" $c "*) continue ;; esac + copies | cut -f2 | grep -qxF "$c" || { echo "FAIL skills: $SK/raea/$c:1: copies a guide that's gone; fix: delete it in raea-skills, or name the guide that replaced it"; fail=1; } + done done - for c in "$SK"/raea/3d/*.md; do - case ${c##*/} in plugins.md | rows.md) continue ;; esac - [ -f "sdk/guides/craft/bevy/${c##*/}" ] || { echo "FAIL skills: $c:1: copies sdk/guides/craft/bevy/${c##*/}, which is gone; fix: delete it in raea-skills, or name the guide that replaced it"; fail=1; } - done + # surface coverage: a warning per verb, SDK entry or feed tool nothing teaches yet (tools/skills.sh coverage lists all) + coverage | awk -F'\t' -v sk="$SK/raea" '$3 == "untaught" { k = $1 == "verb" ? "raea " $2 : $1 == "module" ? "raea/" $2 : "the feed tool " $2; print "skills: coverage: " k " is in raea, but no guide or router says when to use it; fix: teach it in the router for its domain (" sk "/DOMAIN.md) or its guide (sdk/guides/craft), or add it to COVERAGE_SKIP with why" }' # 2. retired words (docs/skills.glossary.md), whole words where they start with a letter local words g=${RAEA_GLOSSARY:-docs/skills.glossary.md} # the glossary is the maintainers' (private); without it, no retired words words=$( [ -f "$g" ] && sed -n '//,//p' "$g" | sed '1d;$d' || true ) @@ -361,7 +414,7 @@ case "${1:-}" in gen_files > "$OUT/files.md" gen_sdk > "$OUT/sdk.md" gen_app > "$OUT/app.md" - mkdir -p "$BEVY_OUT" && cp sdk/guides/craft/bevy/*.md "$BEVY_OUT/" + copies | while IFS=$'\t' read -r g c; do mkdir -p "$COPY_OUT/$(dirname "$c")" && cp "$g" "$COPY_OUT/$c"; done if [ "$1" = gen ]; then wc -l "$OUT"/*.md; fi ;; check) @@ -369,6 +422,11 @@ case "${1:-}" in [ -x "$R" ] || { echo "FAIL skills: no raea to read the help from (RAEA_BIN, or build raea-cli)"; exit 1; } check ;; + coverage) + R=$(raea_bin) + [ -x "$R" ] || { echo "skills.sh: no raea to read the help from (RAEA_BIN, or build raea-cli)" >&2; exit 2; } + coverage | awk -F'\t' '{ n[$1]++; if ($3 == "untaught") { u[$1]++; l[$1] = l[$1] " " $2 } } END { for (k in n) printf "%-7s %3d of %3d taught%s\n", k, n[k] - u[k], n[k], u[k] ? "; untaught:" l[k] : "" }' | sort + ;; check-cli) R=$(raea_bin) [ -x "$R" ] || { echo "FAIL skills: no raea to read the help from (RAEA_BIN, or build raea-cli)"; exit 1; }