Files
holocron/tests/test-skill-size-check.sh
Defame1297 4a5c3c0cff feat(kyberforge): enforce the ADR-0020 context contract for skills and agents
Skill name+description pairs are preloaded into every session, costing
~6,200 tokens across 39 skills before any skill is invoked. The authoring
rules mandated that growth: skill-author:104 and description-quality.md:21
both required padding, while skill-author:102 (the deflating rule) had no
FAIL condition behind it.

Gates (blocking, no baseline file):
- description 250 chars SUGGESTION / 400 FAIL, measured on the folded
  YAML value
- body-only 600 words SUGGESTION / 900 FAIL, independent of the unchanged
  whole-file 2770-word / 500-line spec backstop
- every boundary-clause routing target must resolve to a real skill or
  agent; catches skill-improve, neuledge-context and gitea-labels
- agents take the description gates but deliberately no body gate; a test
  pins that absence

Vale: DescriptionOpener widened to ^This\b, new CompositionNote rule
banning architecture notes from descriptions. 10 hits, 0 false positives.

Kyberforge's own four skills retrofitted: descriptions 3,364 -> 938 chars
(-72%), bodies 8,306 -> 2,487 words (-70%), all via the apm-workflow
dispatch pattern. Fixes the skill-improve dangling route and the
agent-author misroute to manual review.

Also fixes a pre-existing false positive where any line-initial 'read '
was flagged as interactive input, which had already caused two scripts to
be rewritten around it.

Refs: ADR-0020
2026-08-14 21:13:13 +00:00

462 lines
19 KiB
Bash
Executable File

#!/usr/bin/env bash
# Regression test for scripts/skill-size-check.sh, which enforces two
# independent gate families that must not be conflated:
#
# * agentskills.io spec conformance — 500 lines and a 5,000-token ceiling
# enforced via a word-count proxy (MAX_WORDS, currently 2770) over the
# WHOLE FILE, frontmatter included.
# * ADR-0020 context budget — description 250 chars SUGGESTION / 400 FAIL,
# body-ONLY 600 words SUGGESTION / 900 FAIL, and resolvable boundary-clause
# routing targets.
#
# The constant-agreement block below is the load-bearing part: all three copies
# (this hook, skill-audit's validate.sh, agent-audit's validate.sh) are
# hand-duplicated because a cache-installed plugin cannot read outside its own
# directory, and nothing but these assertions stops them drifting.
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
SCRIPT="$REPO_ROOT/scripts/skill-size-check.sh"
VALIDATE="$REPO_ROOT/plugins/kyberforge/.apm/skills/skill-audit/scripts/validate.sh"
AGENT_VALIDATE="$REPO_ROOT/plugins/kyberforge/.apm/skills/agent-audit/scripts/validate.sh"
PASS=0
FAIL=0
pass() { echo " PASS: $1"; PASS=$((PASS + 1)); }
fail() { echo " FAIL: $1"; FAIL=$((FAIL + 1)); }
TMPDIR="$(mktemp -d)"
trap 'rm -rf "$TMPDIR"' EXIT
make_fixture() {
local name="$1" lines="$2" words_per_line="$3" file
file="$TMPDIR/$name.md"
{
echo "---"
echo "name: $name"
echo "description: Test fixture."
echo "---"
for ((i = 1; i <= lines; i++)); do
w=""
for ((j = 1; j <= words_per_line; j++)); do
w="$w word"
done
echo "$w"
done
} > "$file"
echo "$file"
}
echo ""
echo "--- passes a file under both limits ---"
SMALL="$(make_fixture small 10 5)"
if "$SCRIPT" "$SMALL"; then
pass "file under both limits exits 0"
else
fail "file under both limits should have exited 0"
fi
echo ""
echo "--- fails a file over the line limit ---"
MANY_LINES="$(make_fixture many-lines 600 1)"
if "$SCRIPT" "$MANY_LINES" 2>/dev/null; then
fail "file over the 500-line ceiling should have exited non-zero"
else
pass "file over the 500-line ceiling exits non-zero"
fi
echo ""
echo "--- fails a file over the word-count limit ---"
MANY_WORDS="$(make_fixture many-words 10 600)"
if "$SCRIPT" "$MANY_WORDS" 2>/dev/null; then
fail "file over the word ceiling should have exited non-zero"
else
pass "file over the word ceiling exits non-zero"
fi
# Boundary-pair tests below read the script's current MAX_WORDS rather than
# hardcoding it, so they don't silently drift if the threshold changes again.
MAX_WORDS="$(grep -oE '^MAX_WORDS=[0-9]+' "$SCRIPT" | cut -d= -f2)"
MAX_LINES="$(grep -oE '^MAX_LINES=[0-9]+' "$SCRIPT" | cut -d= -f2)"
# The audit (skill-audit/scripts/validate.sh) duplicates both ceilings, because
# a cache-installed plugin's scripts cannot read files outside the plugin
# directory. Nothing but this assertion stops the copies drifting, and drift
# means a SKILL.md passes its own audit and is then rejected by the commit hook.
echo ""
echo "--- the hook and skill-audit's validate.sh agree on both ceilings ---"
if [[ ! -f "$VALIDATE" ]]; then
fail "skill-audit validate.sh not found at $VALIDATE"
else
V_MAX_WORDS="$(grep -oE '^MAX_WORDS = [0-9]+' "$VALIDATE" | grep -oE '[0-9]+')"
V_MAX_LINES="$(grep -oE '^MAX_LINES = [0-9]+' "$VALIDATE" | grep -oE '[0-9]+')"
if [[ "$V_MAX_WORDS" == "$MAX_WORDS" ]]; then
pass "both enforce MAX_WORDS=$MAX_WORDS"
else
fail "MAX_WORDS drift: hook says $MAX_WORDS, validate.sh says ${V_MAX_WORDS:-<unset>}"
fi
if [[ "$V_MAX_LINES" == "$MAX_LINES" ]]; then
pass "both enforce MAX_LINES=$MAX_LINES"
else
fail "MAX_LINES drift: hook says $MAX_LINES, validate.sh says ${V_MAX_LINES:-<unset>}"
fi
fi
# ---------------------------------------------------------------------------
# ADR-0020 constants
# ---------------------------------------------------------------------------
# Three hand-maintained copies, for the same cache-isolation reason as
# MAX_WORDS/MAX_LINES above. skill-audit carries all four; agent-audit carries
# only the two description constants, because ADR-0020 deliberately gives
# agents NO body word gate (a skill body competes with the caller's live
# conversation; an agent body becomes the system prompt of a fresh context).
# The absence of BODY_* in agent-audit is asserted below so a well-meaning
# "consistency" edit that adds them fails here rather than contradicting the
# ADR silently.
DESC_SUGGEST_CHARS="$(grep -oE '^DESC_SUGGEST_CHARS=[0-9]+' "$SCRIPT" | cut -d= -f2)"
DESC_MAX_CHARS="$(grep -oE '^DESC_MAX_CHARS=[0-9]+' "$SCRIPT" | cut -d= -f2)"
BODY_SUGGEST_WORDS="$(grep -oE '^BODY_SUGGEST_WORDS=[0-9]+' "$SCRIPT" | cut -d= -f2)"
BODY_MAX_WORDS="$(grep -oE '^BODY_MAX_WORDS=[0-9]+' "$SCRIPT" | cut -d= -f2)"
echo ""
echo "--- the hook declares all four ADR-0020 constants ---"
for pair in "DESC_SUGGEST_CHARS:$DESC_SUGGEST_CHARS" "DESC_MAX_CHARS:$DESC_MAX_CHARS" \
"BODY_SUGGEST_WORDS:$BODY_SUGGEST_WORDS" "BODY_MAX_WORDS:$BODY_MAX_WORDS"; do
if [[ -n "${pair#*:}" ]]; then
pass "${pair%%:*}=${pair#*:}"
else
fail "${pair%%:*} is not declared in $SCRIPT"
fi
done
echo ""
echo "--- the hook and skill-audit's validate.sh agree on all four ADR-0020 constants ---"
for const in DESC_SUGGEST_CHARS DESC_MAX_CHARS BODY_SUGGEST_WORDS BODY_MAX_WORDS; do
hook_value="$(grep -oE "^${const}=[0-9]+" "$SCRIPT" | cut -d= -f2)"
audit_value="$(grep -oE "^${const} = [0-9]+" "$VALIDATE" | grep -oE '[0-9]+' || true)"
if [[ -n "$hook_value" && "$hook_value" == "$audit_value" ]]; then
pass "both enforce $const=$hook_value"
else
fail "$const drift: hook says ${hook_value:-<unset>}, skill-audit validate.sh says ${audit_value:-<unset>}"
fi
done
echo ""
echo "--- the hook and agent-audit's validate.sh agree on the description constants ---"
if [[ ! -f "$AGENT_VALIDATE" ]]; then
fail "agent-audit validate.sh not found at $AGENT_VALIDATE"
else
for const in DESC_SUGGEST_CHARS DESC_MAX_CHARS; do
hook_value="$(grep -oE "^${const}=[0-9]+" "$SCRIPT" | cut -d= -f2)"
agent_value="$(grep -oE "^${const} = [0-9]+" "$AGENT_VALIDATE" | grep -oE '[0-9]+' || true)"
if [[ -n "$hook_value" && "$hook_value" == "$agent_value" ]]; then
pass "both enforce $const=$hook_value"
else
fail "$const drift: hook says ${hook_value:-<unset>}, agent-audit validate.sh says ${agent_value:-<unset>}"
fi
done
echo ""
echo "--- agent-audit declares NO body word gate (ADR-0020 is explicit about this) ---"
if grep -qE '^BODY_(SUGGEST|MAX)_WORDS = ' "$AGENT_VALIDATE"; then
fail "agent-audit validate.sh declares a body word gate — ADR-0020 gives agents the description gates and NO body word gate"
else
pass "agent-audit validate.sh declares no BODY_*_WORDS constant"
fi
fi
# make_line_fixture builds a file with an exact total line count (frontmatter
# included), independent of word count, for the line-boundary tests.
make_line_fixture() {
local name="$1" total_lines="$2" file body_lines
file="$TMPDIR/$name.md"
{
echo "---"
echo "name: $name"
echo "description: Test fixture."
echo "---"
} > "$file"
body_lines=$((total_lines - 4))
for ((i = 1; i <= body_lines; i++)); do
echo "word"
done >> "$file"
echo "$file"
}
# The line ceiling is inclusive of the limit itself, enforced via `>` — so
# exactly $MAX_LINES must pass and $((MAX_LINES + 1)) must fail. This matches
# skill-audit/scripts/validate.sh's `line_count <= 500` pass condition; the two
# previously disagreed at exactly $MAX_LINES lines, so a SKILL.md could pass its
# own audit and still be blocked by the commit hook.
echo ""
echo "--- passes a file at exactly the $MAX_LINES-line boundary ---"
AT_LINES="$(make_line_fixture at-line-limit "$MAX_LINES")"
ACTUAL_LINES=$(awk 'END{print NR}' "$AT_LINES")
if [[ "$ACTUAL_LINES" -ne "$MAX_LINES" ]]; then
fail "fixture has $ACTUAL_LINES lines, expected exactly $MAX_LINES"
elif "$SCRIPT" "$AT_LINES"; then
pass "file at exactly $MAX_LINES lines exits 0"
else
fail "file at exactly $MAX_LINES lines should have exited 0 (the off-by-one this test guards against)"
fi
echo ""
echo "--- fails a file one line over the $MAX_LINES-line boundary ---"
OVER_LINES="$(make_line_fixture over-line-limit "$((MAX_LINES + 1))")"
ACTUAL_OVER_LINES=$(awk 'END{print NR}' "$OVER_LINES")
if [[ "$ACTUAL_OVER_LINES" -ne "$((MAX_LINES + 1))" ]]; then
fail "fixture has $ACTUAL_OVER_LINES lines, expected exactly $((MAX_LINES + 1))"
elif "$SCRIPT" "$OVER_LINES" 2>/dev/null; then
fail "file at $((MAX_LINES + 1)) lines should have exited non-zero"
else
pass "file at $((MAX_LINES + 1)) lines exits non-zero"
fi
# make_word_fixture builds a file with an exact total word count (frontmatter
# words included, since the script's `wc -w` counts the whole file).
#
# The padding goes in a frontmatter `notes:` field, NOT in the body, and that
# placement is the point: MAX_WORDS is a whole-file measurement while ADR-0020's
# BODY_MAX_WORDS is a body-only one. Padding the body would make a 2,770-word
# fixture trip the 900-word body ceiling too, and the MAX_WORDS boundary test
# would stop isolating MAX_WORDS. `notes:` is an unused key — the description
# stays short, so the description gate stays quiet as well.
make_word_fixture() {
local name="$1" target="$2" file frame_words padding
file="$TMPDIR/$name.md"
padding=""
{
echo "---"
echo "name: $name"
echo "description: Test fixture."
echo "notes:$padding"
echo "---"
echo ""
echo "Body."
} > "$file"
frame_words=$(wc -w < "$file")
for ((i = 1; i <= target - frame_words; i++)); do
padding="$padding word"
done
{
echo "---"
echo "name: $name"
echo "description: Test fixture."
echo "notes:$padding"
echo "---"
echo ""
echo "Body."
} > "$file"
echo "$file"
}
echo ""
echo "--- passes a file at exactly the $MAX_WORDS-word boundary ---"
AT_WORDS="$(make_word_fixture at-word-limit "$MAX_WORDS")"
ACTUAL_WORDS=$(wc -w < "$AT_WORDS")
if [[ "$ACTUAL_WORDS" -ne "$MAX_WORDS" ]]; then
fail "fixture has $ACTUAL_WORDS words, expected exactly $MAX_WORDS"
elif "$SCRIPT" "$AT_WORDS"; then
pass "file at exactly $MAX_WORDS words exits 0"
else
fail "file at exactly $MAX_WORDS words should have exited 0"
fi
echo ""
echo "--- fails a file one word over the $MAX_WORDS-word boundary ---"
OVER_WORDS="$(make_word_fixture over-word-limit "$((MAX_WORDS + 1))")"
ACTUAL_OVER_WORDS=$(wc -w < "$OVER_WORDS")
if [[ "$ACTUAL_OVER_WORDS" -ne "$((MAX_WORDS + 1))" ]]; then
fail "fixture has $ACTUAL_OVER_WORDS words, expected exactly $((MAX_WORDS + 1))"
elif "$SCRIPT" "$OVER_WORDS" 2>/dev/null; then
fail "file at $((MAX_WORDS + 1)) words should have exited non-zero"
else
pass "file at $((MAX_WORDS + 1)) words exits non-zero"
fi
# ---------------------------------------------------------------------------
# ADR-0020 behaviour
# ---------------------------------------------------------------------------
# make_budget_fixture builds a SKILL.md with a verbatim description and an
# exact BODY word count (frontmatter words excluded — the ADR-0020 body gate
# counts the body only).
make_budget_fixture() {
local name="$1" desc="$2" body_words="$3" file
file="$TMPDIR/$name.md"
{
echo "---"
echo "name: $name"
echo "description: $desc"
echo "---"
echo ""
python3 -c "print(' '.join(['word'] * $body_words))"
} > "$file"
echo "$file"
}
# expect_gate <label> <expected: pass|suggest|fail> <file> [needle]
expect_gate() {
local label="$1" expected="$2" file="$3" needle="${4:-}" out status
set +e
out="$("$SCRIPT" "$file" 2>&1)"
status=$?
set -e
case "$expected" in
pass)
if [[ $status -eq 0 && -z "$out" ]]; then
pass "$label"
else
fail "$label (exit $status, output: ${out:-<empty>})"
fi
;;
suggest)
if [[ $status -eq 0 && "$out" == *"SUGGESTION"* && "$out" == *"$needle"* ]]; then
pass "$label"
else
fail "$label (exit $status, output: ${out:-<empty>})"
fi
;;
fail)
if [[ $status -ne 0 && "$out" == *"$needle"* ]]; then
pass "$label"
else
fail "$label (exit $status, output: ${out:-<empty>})"
fi
;;
esac
}
echo ""
echo "--- description budget: $DESC_SUGGEST_CHARS SUGGESTION / $DESC_MAX_CHARS FAIL, both inclusive ---"
D_AT_SUGGEST="$(python3 -c "print('x' * $DESC_SUGGEST_CHARS)")"
D_OVER_SUGGEST="$(python3 -c "print('x' * $((DESC_SUGGEST_CHARS + 1)))")"
D_AT_MAX="$(python3 -c "print('x' * $DESC_MAX_CHARS)")"
D_OVER_MAX="$(python3 -c "print('x' * $((DESC_MAX_CHARS + 1)))")"
expect_gate "description at exactly $DESC_SUGGEST_CHARS chars is silent" \
pass "$(make_budget_fixture desc-at-suggest "$D_AT_SUGGEST" 10)"
expect_gate "description at $((DESC_SUGGEST_CHARS + 1)) chars suggests and exits 0" \
suggest "$(make_budget_fixture desc-over-suggest "$D_OVER_SUGGEST" 10)" \
"description is $((DESC_SUGGEST_CHARS + 1)) characters"
expect_gate "description at exactly $DESC_MAX_CHARS chars suggests, does not fail" \
suggest "$(make_budget_fixture desc-at-max "$D_AT_MAX" 10)" \
"description is $DESC_MAX_CHARS characters"
expect_gate "description at $((DESC_MAX_CHARS + 1)) chars fails" \
fail "$(make_budget_fixture desc-over-max "$D_OVER_MAX" 10)" \
"$DESC_MAX_CHARS-character ceiling"
echo ""
echo "--- description length is measured after YAML folding is resolved ---"
FOLDED="$TMPDIR/folded.md"
{
echo "---"
echo "name: folded"
echo "description: >"
python3 -c "print('\n'.join([' ' + 'x' * 40] * 11))"
echo "---"
echo ""
echo "Do the thing."
} > "$FOLDED"
expect_gate "a >-folded 450-char description fails (raw first line would read as 1 char)" \
fail "$FOLDED" "description is 450 characters"
echo ""
echo "--- body budget: $BODY_SUGGEST_WORDS SUGGESTION / $BODY_MAX_WORDS FAIL, body only, both inclusive ---"
expect_gate "body at exactly $BODY_SUGGEST_WORDS words is silent" \
pass "$(make_budget_fixture body-at-suggest "Short valid description." "$BODY_SUGGEST_WORDS")"
expect_gate "body at $((BODY_SUGGEST_WORDS + 1)) words suggests and exits 0" \
suggest "$(make_budget_fixture body-over-suggest "Short valid description." "$((BODY_SUGGEST_WORDS + 1))")" \
"body is $((BODY_SUGGEST_WORDS + 1)) words"
expect_gate "body at exactly $BODY_MAX_WORDS words suggests, does not fail" \
suggest "$(make_budget_fixture body-at-max "Short valid description." "$BODY_MAX_WORDS")" \
"body is $BODY_MAX_WORDS words"
expect_gate "body at $((BODY_MAX_WORDS + 1)) words fails" \
fail "$(make_budget_fixture body-over-max "Short valid description." "$((BODY_MAX_WORDS + 1))")" \
"$BODY_MAX_WORDS-word ceiling"
# The two word gates measure different things and must stay separable: a file
# whose FRONTMATTER pushes the whole-file count past the body ceiling must not
# trip the body gate, and a file under MAX_WORDS can still fail the body gate.
echo ""
echo "--- the body gate and the whole-file gate are independent measurements ---"
BODY_ONLY_DESC="$(python3 -c "print(' '.join(['w'] * 100))")"
expect_gate "frontmatter words do not count toward the $BODY_MAX_WORDS-word body ceiling" \
suggest "$(make_budget_fixture body-independent "$BODY_ONLY_DESC" "$((BODY_MAX_WORDS - 5))")" \
"words"
BIG_BODY="$(make_budget_fixture body-over-not-whole-file "Short valid description." "$((BODY_MAX_WORDS + 1))")"
BIG_BODY_WORDS="$(wc -w < "$BIG_BODY")"
if [[ "$BIG_BODY_WORDS" -le "$MAX_WORDS" ]]; then
pass "the body-gate fixture is $BIG_BODY_WORDS whole-file words, well under MAX_WORDS=$MAX_WORDS — it fails on the body gate alone"
else
fail "the body-gate fixture is $BIG_BODY_WORDS whole-file words, which also trips MAX_WORDS=$MAX_WORDS — the test no longer isolates the body gate"
fi
echo ""
echo "--- resolvable boundary targets ---"
# Resolution is against the AUTHORING SOURCE (plugins/*/.apm/skills/ and
# plugins/*/.apm/agents/), found here via the script's own repo root — these
# fixtures live in a temp dir with no plugin tree of their own, so a resolving
# target proves the repo-root path works.
expect_gate "a boundary target naming a real skill resolves" \
pass "$(make_budget_fixture target-ok \
"Use when doing the thing. Do not use for commits — use git-commits instead." 10)"
expect_gate "a boundary target naming a real AGENT resolves (agents are valid targets)" \
pass "$(make_budget_fixture target-agent-ok \
"Use when doing the thing. Do not use when the caller is an agent — invoke git-orchestrate instead." 10)"
expect_gate "a boundary target that resolves to nothing fails" \
fail "$(make_budget_fixture target-missing \
"Use when doing the thing. Do not use for improvements — use no-such-skill-anywhere instead." 10)" \
"routes to 'no-such-skill-anywhere'"
expect_gate "a /slash-command boundary target that resolves to nothing fails" \
fail "$(make_budget_fixture target-missing-slash \
"Use when doing the thing. Do not use for improvements — use /no-such-slash-skill instead." 10)" \
"routes to 'no-such-slash-skill'"
# False-positive guards. These phrasings are lifted from real descriptions:
# pc-run says "run pre-commit hooks", diagnose chains "fix -> regression-test",
# gitea-files says "(use Read/Write/Edit)", gitea-labels-milestones says
# "through `issue_write`/`pull_request_write`". None of them is a routing
# target, and reading any of them as one makes the gate untrustworthy.
expect_gate "'run pre-commit hooks' outside a boundary sentence is not a routing target" \
pass "$(make_budget_fixture fp-precommit \
"Use when the user wants to run pre-commit hooks or install git hooks." 10)"
expect_gate "an arrow chain outside a boundary clause is not a routing target" \
pass "$(make_budget_fixture fp-arrow \
"Reproduce → minimise → instrument → fix → regression-test. Use when a bug is reported." 10)"
expect_gate "tool names and MCP tool names are not routing targets" \
pass "$(make_budget_fixture fp-tools \
"Use when writing issues. Do not use for local files (use Read/Write/Edit) — that write goes through \`issue_write\`/\`pull_request_write\` instead." 10)"
echo ""
echo "--- the three live dangling routing targets are caught (issue #100) ---"
# ADR-0020 records four broken routing targets and splits fixing them into its
# own issue. Three are detectable from the description text alone; this asserts
# the gate actually sees them rather than the check being vacuous in the corpus
# it was written against.
for probe in \
"plugins/bin/.apm/skills/research/SKILL.md:neuledge-context" \
"plugins/kyberforge/.apm/skills/skill-audit/SKILL.md:skill-improve" \
"plugins/gitea/.apm/skills/gitea-issues/SKILL.md:gitea-labels"; do
probe_file="$REPO_ROOT/${probe%%:*}"
probe_name="${probe##*:}"
if [[ ! -f "$probe_file" ]]; then
pass "SKIP: ${probe%%:*} no longer exists (retrofitted)"
continue
fi
# Captured, not piped: the script exits non-zero on these files and
# `set -o pipefail` would make the whole pipeline non-zero regardless of what
# grep found.
set +e
probe_out="$("$SCRIPT" "$probe_file" 2>&1)"
set -e
if [[ "$probe_out" == *"routes to '$probe_name'"* ]]; then
pass "detects the dangling '$probe_name' target in ${probe%%:*}"
elif ! grep -q "$probe_name" "$probe_file"; then
pass "SKIP: '$probe_name' no longer appears in ${probe%%:*} (fixed by issue #100)"
else
fail "did not detect the dangling '$probe_name' target in ${probe%%:*}"
fi
done
echo ""
echo "Results: $PASS passed, $FAIL failed"
[[ $FAIL -eq 0 ]]