refactor(skills): retrofit the corpus to the ADR-0020 context contract (#129)
Retrofits all 39 skills to ADR-0020's description/body context contract, then fixes what six rounds of independent review found in that retrofit — including four ways the hot gate itself failed open. Closes #99, #107, #108, #110, #111, #114, #115, #120. ## The retrofit (waves 1-5) | | Start | Now | |---|---|---| | Description FAILs (>400 chars) | 26 | **0** | | Body FAILs (>900 words, body-only) | 9 | **0** | | Dangling routing targets | 2 | **0** | | `Kyberforge.CompositionNote` | 10 | **0** | | Preload tax | 21,005 chars | **~10,500** | Under the 12,000-char success criterion. Per-wave detail is on #99. ## The review fixes **The gate failed open four ways, three of them found after the retrofit shipped.** An unrecognised follower token made a dangling target vanish. A skill directory with no `SKILL.md` resolved as a valid target, so a commit could be green locally and red in a fresh clone — three existing fixtures were relying on that, one of which made the install-leak A/B pass vacuously. Then the free-standing `/name` sweep turned out to be gated on the sentence carrying a boundary marker, so route notation in any other sentence was invisible — not an ERROR, not a SUGGESTION, not an INFO — which left the documented "`/name` always blocks" promise false from a second direction. All four fixed and pinned. **Two checks were silently not running.** `validate-provenance.sh` checks 7-8 were dead across nine skills. Waking them exposed a deeper problem: they assume `Research doc:` names a source index, but 30 of 121 entries point at topic content documents, so every new check-7 INFO was a false positive and check 8 was saved from a false-FAIL flood only by an *unannounced* skip. Checks 7/8 are now scoped to source indexes and every skip announces itself (#121). **The retrofit's own anti-goal, four times.** ADR-0020 warns that a blunt gate gets satisfied by deleting content rather than relocating it. `diagnose` and `skill-audit` relocated prose and then read it unconditionally; `prototype` and `vale-config` deleted rules outright that survived nowhere. All four addressed. ## Verification - `bash tests/run-tests.sh --strict` — 24 suites, 0 skipped, 0 failed - `bash tests/run-bats.sh` — 325 tests, 0 failures - `pre-commit run --all-files` — 17/17 - `pre-commit run --hook-stage pre-push --all-files` — 16/16, with `apm marketplace check` and `apm pack --check-clean` run against the remote, not skipped - `scripts/skill-size-check.sh` over all 39 skills — rc 0, 0 ERROR/FAIL, SUGGESTION-only - Preload tax measured at **10,498 chars**, max description 390 — both inside budget - Every new test proven non-vacuous by a deliberate mutation of the behaviour it covers **Per-commit sync, stated accurately:** the ten commits from the latest review round each pass `check-plugin-content-sync` in isolation, verified by checking each out in a detached worktree with a clean between. The earlier gitea window (`dfacf05..bedbd1d`, nine commits) does **not** — its mirror was regenerated in one batch at `bbc7300`. An earlier revision of this description claimed the property held for every commit; it does not, and a bisect through that window lands on a red commit. **Squash-merge** to collapse it, or accept that this range is not bisectable. ## Version bump Six plugins and the catalog take a **patch**, not a minor. The branch is **89 commits — 40 `fix` / 30 `refactor` / 12 `docs` / 5 `chore` / 2 `test` — zero `feat`, zero `!`, zero `BREAKING CHANGE`** — and adds no skill, agent, command or hook. (Two earlier revisions of this section cited a stale histogram, most recently 78 commits; the figures above are measured at HEAD.) Both rules this repo ships (`forge/references/version-bump.md`, landing in this PR, and `git-commits/references/conventional-commits-spec.md`) make that a patch, and the catalog set is unchanged at 7 entries. Not settled by that: four published files were removed from the installed tree, three moved, and `caveman` gained `disable-model-invocation`, retiring its old triggers. Under a strict reading those are major-class and currently ship under `refactor:` with no marker. Whether the deployed skill surface is a public contract is written down nowhere — worth deciding, but it outlives this PR. ## Deliberately not in scope #112 (cherry-pick ownership, now resolved in favour of `git-commits`), #113 (`rtk git` normalisation), #116 (research fan-out), #101 (audit-skill merge), #122 (non-spec skill-root files), #123 (no PRD producer) stay open. #117 is the one worth reading: the contract's remedy is to move prose into `references/`, which is exactly where neither the size gate nor Vale looks — and the blind spot is wider than #117 currently records, since there is no root `.vale.ini` at all, so every ADR, `CONTEXT.md` and `README.md` is unlinted too. That blind spot let this branch carry two `level: error` `Kyberforge.SentenceOpenerThereIs` violations into `references/` files it created — `provider-adapter-author/references/provider-matrix.md:31` and `agent-audit/references/finding-criteria.md:95`. Both are reworded in `afadaae`, confirmed by routing each file through the audit's own `vale-wrap.sh` (1 error each before, 0 after). Five further occurrences sit in `references/` files already on `main`; those are the pre-existing corpus and stay with #117, which is the real fix. Also unfixed and not this PR's: `apm install` appends a duplicate `SessionStart` entry to `.claude/settings.json`, so a fresh clone cannot get pre-push green without an edit AGENTS.md warns against. Reproduces identically on `main`. Co-authored-by: Defame1297 <gitea@rkdr.net> Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/129 Co-authored-by: Claude Code AI - Gitea MCP <claude@noreply.git.dev.rkdr.net> Co-committed-by: Claude Code AI - Gitea MCP <claude@noreply.git.dev.rkdr.net>
This commit was merged in pull request #129.
This commit is contained in:
Claude Code AI - Gitea MCP
@@ -92,8 +92,14 @@ build_tree "$TMPDIR_T/no-claude"
|
||||
build_tree "$TMPDIR_T/with-claude"
|
||||
# The deployed tree, present only in the second root. Both a skill and an agent,
|
||||
# because both are valid routing targets and both would leak.
|
||||
mkdir -p "$TMPDIR_T/with-claude/.claude/skills/deployed-only-skill" \
|
||||
"$TMPDIR_T/with-claude/.claude/agents"
|
||||
#
|
||||
# The skill gets a real SKILL.md. That is not decoration: a directory under
|
||||
# skills/ is a resolvable name only when it HOLDS one, so an empty directory
|
||||
# would dangle for the wrong reason and the assertion below would pass without
|
||||
# testing the deployed-tree rule at all.
|
||||
mkdir -p "$TMPDIR_T/with-claude/.claude/agents"
|
||||
write_skill "$TMPDIR_T/with-claude/.claude/skills/deployed-only-skill" deployed-only-skill \
|
||||
"Use when doing the deployed thing. Do not use for anything else."
|
||||
: > "$TMPDIR_T/with-claude/.claude/agents/deployed-only-agent.md"
|
||||
|
||||
run_subject() {
|
||||
@@ -133,7 +139,8 @@ fi
|
||||
echo ""
|
||||
echo "--- with no authoring root, a deployed .claude/ tree IS the universe ---"
|
||||
CONSUMER="$TMPDIR_T/consumer"
|
||||
mkdir -p "$CONSUMER/.claude/skills/deployed-only-skill"
|
||||
write_skill "$CONSUMER/.claude/skills/deployed-only-skill" deployed-only-skill \
|
||||
"Use when doing the deployed thing. Do not use for anything else."
|
||||
write_skill "$CONSUMER/.claude/skills/my-skill" my-skill \
|
||||
"Use when doing the thing. Do not use for the other thing — use deployed-only-skill instead."
|
||||
set +e
|
||||
@@ -362,35 +369,51 @@ cp -R "$REPO_ROOT/plugins" "$FRESH_ROOT/plugins"
|
||||
[[ -f "$REPO_ROOT/apm.yml" ]] && cp "$REPO_ROOT/apm.yml" "$FRESH_ROOT/apm.yml"
|
||||
FRESH_DANGLING="$(dangling_set "$FRESH_ROOT/plugins")"
|
||||
|
||||
DEPLOYED_ROOT="$TMPDIR_T/deployed-clone"
|
||||
mkdir -p "$DEPLOYED_ROOT/.claude/skills" "$DEPLOYED_ROOT/.claude/agents"
|
||||
cp -R "$REPO_ROOT/plugins" "$DEPLOYED_ROOT/plugins"
|
||||
[[ -f "$REPO_ROOT/apm.yml" ]] && cp "$REPO_ROOT/apm.yml" "$DEPLOYED_ROOT/apm.yml"
|
||||
# Deploy exactly the names that currently dangle. That is the strongest possible
|
||||
# bait: if the deployed tree were consulted, every one of them would resolve and
|
||||
# the dangling set would collapse to empty.
|
||||
DEPLOY_COUNT=0
|
||||
while IFS= read -r name; do
|
||||
[[ -n "$name" ]] || continue
|
||||
mkdir -p "$DEPLOYED_ROOT/.claude/skills/$name"
|
||||
DEPLOY_COUNT=$((DEPLOY_COUNT + 1))
|
||||
done <<< "$FRESH_DANGLING"
|
||||
DEPLOYED_DANGLING="$(dangling_set "$DEPLOYED_ROOT/plugins")"
|
||||
# The bait used to be DERIVED from the corpus: deploy exactly the names that
|
||||
# currently dangle. That was the strongest bait available while the corpus had
|
||||
# dangling names — and it silently became vacuous the moment issue #99 fixed the
|
||||
# last one, because a corpus reporting nothing gives nothing to deploy. A test of
|
||||
# "deployed trees do not leak" must not depend on the corpus staying broken.
|
||||
#
|
||||
# So the bait is now EXPLICIT. Both contrast copies get one synthetic skill whose
|
||||
# boundary clause routes to a name guaranteed absent from the monorepo, and only
|
||||
# the deployed copy gets that name planted in .claude/skills/. If deployed trees
|
||||
# leaked into the resolver's universe, the deployed copy would resolve it and
|
||||
# report an empty set while the fresh copy reported one. The A/B now distinguishes
|
||||
# something on every run, forever, whatever the corpus does.
|
||||
BAIT_NAME="no-such-deployed-only-skill"
|
||||
BAIT_FRESH="$TMPDIR_T/bait-fresh"
|
||||
BAIT_DEPLOYED="$TMPDIR_T/bait-deployed"
|
||||
for bait_root in "$BAIT_FRESH" "$BAIT_DEPLOYED"; do
|
||||
mkdir -p "$bait_root"
|
||||
cp -R "$REPO_ROOT/plugins" "$bait_root/plugins"
|
||||
[[ -f "$REPO_ROOT/apm.yml" ]] && cp "$REPO_ROOT/apm.yml" "$bait_root/apm.yml"
|
||||
write_skill "$bait_root/plugins/bin/.apm/skills/deployed-tree-probe" deployed-tree-probe \
|
||||
"Use when doing the probe thing. Do not use for the other thing — use $BAIT_NAME instead."
|
||||
done
|
||||
# Only the deployed copy gets the name planted where `apm install` would put it,
|
||||
# as a REAL skill directory holding a SKILL.md — an empty directory is not a
|
||||
# resolvable name, so baiting with one would make the A/B pass vacuously.
|
||||
mkdir -p "$BAIT_DEPLOYED/.claude/agents"
|
||||
write_skill "$BAIT_DEPLOYED/.claude/skills/$BAIT_NAME" "$BAIT_NAME" \
|
||||
"Use when doing the bait thing. Do not use for anything else."
|
||||
BAIT_FRESH_DANGLING="$(dangling_set "$BAIT_FRESH/plugins")"
|
||||
BAIT_DEPLOYED_DANGLING="$(dangling_set "$BAIT_DEPLOYED/plugins")"
|
||||
|
||||
if [[ "$DEPLOY_COUNT" -gt 0 ]]; then
|
||||
pass "precondition: $DEPLOY_COUNT dangling name(s) deployed into the contrast tree's .claude/skills/, so the A/B has something to distinguish"
|
||||
if [[ "$BAIT_FRESH_DANGLING" == *"$BAIT_NAME"* ]]; then
|
||||
pass "precondition: the bait target dangles in the un-deployed copy, so the A/B has something to distinguish"
|
||||
else
|
||||
fail "no dangling names to deploy — the corpus reports none, so this A/B distinguishes nothing. Deploy a known-absent name explicitly instead of deriving one."
|
||||
fail "the bait target '$BAIT_NAME' does not dangle even without a deployed tree — the fixture is broken, so the contrast below proves nothing. Got: [$(echo "$BAIT_FRESH_DANGLING" | tr '\n' ' ')]"
|
||||
fi
|
||||
if [[ ! -d "$FRESH_ROOT/.claude" && ! -d "$FRESH_ROOT/.agents" ]]; then
|
||||
if [[ ! -d "$BAIT_FRESH/.claude" && ! -d "$BAIT_FRESH/.agents" ]]; then
|
||||
pass "precondition: the fresh-clone copy has no deployed tree of its own"
|
||||
else
|
||||
fail "the fresh-clone copy picked up a deployed tree — it is not a fresh-clone fixture"
|
||||
fi
|
||||
if [[ "$FRESH_DANGLING" == "$DEPLOYED_DANGLING" ]]; then
|
||||
pass "deploying every dangling name into .claude/skills/ changes nothing: $(echo "$FRESH_DANGLING" | tr '\n' ' ')"
|
||||
if [[ "$BAIT_FRESH_DANGLING" == "$BAIT_DEPLOYED_DANGLING" ]]; then
|
||||
pass "planting the dangling name in .claude/skills/ changes nothing: $(echo "$BAIT_DEPLOYED_DANGLING" | tr '\n' ' ')"
|
||||
else
|
||||
fail "the corpus verdict depends on whether apm install has been run — fresh clone: [$(echo "$FRESH_DANGLING" | tr '\n' ' ')] with a deployed tree: [$(echo "$DEPLOYED_DANGLING" | tr '\n' ' ')]"
|
||||
fail "the verdict depends on whether apm install has been run — fresh clone: [$(echo "$BAIT_FRESH_DANGLING" | tr '\n' ' ')] with a deployed tree: [$(echo "$BAIT_DEPLOYED_DANGLING" | tr '\n' ' ')]. A deployed .claude/skills/ tree is leaking into the resolver's universe."
|
||||
fi
|
||||
# Third data point: whatever state THIS machine happens to be in, the live tree
|
||||
# must agree with a bare copy of the same plugins/. No precondition on that state
|
||||
@@ -410,41 +433,40 @@ fi
|
||||
# rather than a "contains" — a false-positive fix that suppressed one of them
|
||||
# would otherwise land green.
|
||||
#
|
||||
# `gitea-labels` is the subtler of the two and is worth keeping: it is not
|
||||
# written anywhere as `gitea-labels`. gitea-issues' description says "Composes
|
||||
# `gitea-labels-\n milestones`" in a `>`-folded scalar, and the fold joins the
|
||||
# lines into "gitea-labels- milestones" — the trailing hyphen is what keeps the
|
||||
# token terminal and therefore danglable.
|
||||
# `gitea-labels` WAS the subtler of the two: it was never written anywhere as
|
||||
# `gitea-labels`. gitea-issues' description said "Composes `gitea-labels-\n
|
||||
# milestones`" in a `>`-folded scalar, and the fold joined the lines into
|
||||
# "gitea-labels- milestones" — the trailing hyphen is what kept the token
|
||||
# terminal and therefore danglable. The issue #99 retrofit cut that composition
|
||||
# sentence and the dangling target went with it, so the set is down to one.
|
||||
#
|
||||
# WHEN ISSUE #100 IS FIXED: update EXPECTED_DANGLING to match. Do not delete the
|
||||
# assertion — an empty expected set is fine and still pins that no NEW dangling
|
||||
# target appeared.
|
||||
# `neuledge-context` was the last one. The issue #99 wave-3 retrofit deleted that
|
||||
# boundary clause outright — commit `6146120` had already deleted the skill it
|
||||
# named, and nothing has owned MCP-server installation since — so the corpus
|
||||
# dangling set is now EMPTY.
|
||||
#
|
||||
# The assertion stays, and it is not vacuous now that it expects nothing: it is
|
||||
# the only thing standing between a newly-authored boundary clause naming a
|
||||
# non-existent target and a green suite. An empty expected set pins "no NEW
|
||||
# dangling target appeared", which is the property that actually matters from
|
||||
# here on.
|
||||
#
|
||||
# The per-target probe loop that used to sit below is GONE, not emptied. Its job
|
||||
# was to prove the check detects each live dangling target individually, and with
|
||||
# no live targets left there is nothing to point it at. A loop over an empty list
|
||||
# is an assertion-free result counted in the totals — exactly the vacuous-pass
|
||||
# shape the comment above rejects. Detection is still covered, and covered
|
||||
# better, by the synthetic fixtures in section 2 below, which build a real plugin
|
||||
# tree and assert the resolver fires. Do not reinstate the loop unless a real
|
||||
# dangling target reappears in the corpus.
|
||||
echo ""
|
||||
echo "--- the two live dangling targets in the corpus are exactly the two ADR-0020 records ---"
|
||||
EXPECTED_DANGLING="$(printf '%s\n' gitea-labels neuledge-context)"
|
||||
echo "--- no skill in the corpus routes to a target that does not resolve ---"
|
||||
EXPECTED_DANGLING=""
|
||||
if [[ "$LIVE_DANGLING" == "$EXPECTED_DANGLING" ]]; then
|
||||
pass "the corpus dangling set is exactly {gitea-labels, neuledge-context}"
|
||||
pass "the corpus dangling set is empty"
|
||||
else
|
||||
fail "the corpus dangling set changed — expected [$(echo "$EXPECTED_DANGLING" | tr '\n' ' ')], got [$(echo "$LIVE_DANGLING" | tr '\n' ' ')]. If a retrofit fixed one, update EXPECTED_DANGLING; if a false-positive fix silently deleted one, that is the regression this asserts."
|
||||
fail "a dangling routing target appeared in the corpus — expected none, got [$(echo "$LIVE_DANGLING" | tr '\n' ' ')]. A boundary clause names a skill or agent that does not resolve; fix the clause or the target. This assertion is the corpus-wide backstop, so do not relax it to make a new skill pass."
|
||||
fi
|
||||
for probe in \
|
||||
"plugins/bin/.apm/skills/research/SKILL.md:neuledge-context" \
|
||||
"plugins/gitea/.apm/skills/gitea-issues/SKILL.md:gitea-labels"; do
|
||||
probe_file="$REPO_ROOT/${probe%%:*}"
|
||||
probe_name="${probe##*:}"
|
||||
if [[ ! -f "$probe_file" ]]; then
|
||||
fail "the true-positive fixture ${probe%%:*} no longer exists — this pin has become vacuous"
|
||||
continue
|
||||
fi
|
||||
set +e
|
||||
probe_out="$(bash "$HOOK" "$probe_file" 2>&1)"
|
||||
set -e
|
||||
if [[ "$probe_out" == *"routes to '$probe_name'"* ]]; then
|
||||
pass "detects the dangling '$probe_name' target in ${probe%%:*}"
|
||||
else
|
||||
fail "did not detect the dangling '$probe_name' target in ${probe%%:*} — a false-positive fix has taken a true positive with it: $probe_out"
|
||||
fi
|
||||
done
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2. The bare-target grammar rule
|
||||
@@ -500,13 +522,24 @@ grammar_case() {
|
||||
|
||||
# The four phrasings that were hard dangling FAILs with no suppression. All four
|
||||
# are lifted from real descriptions in this corpus.
|
||||
grammar_case fp-precommit-hooks silent "" \
|
||||
#
|
||||
# THEY ARE `suggests`, NOT `silent`, AND THE DIFFERENCE IS THE POINT. The
|
||||
# follower rule takes away the power to BLOCK a commit on a compound modifier;
|
||||
# it does not take away visibility, and it used to. FOLLOWER_OK is a closed
|
||||
# whitelist of about eighty words, so a non-terminal verdict means "the next
|
||||
# token is outside a list someone maintains by hand", not "this is prose" — and
|
||||
# `continue`ing on it made the gate fail OPEN on its own unfamiliarity: any
|
||||
# target followed by an unlisted word was neither blocked nor mentioned at any
|
||||
# tier. Asserting silence here pinned that hole in place. The assertion that
|
||||
# still matters is `!= ERROR`, which `suggests` checks, and which is what keeps
|
||||
# a false positive from stopping a commit.
|
||||
grammar_case fp-precommit-hooks suggests "routes to 'pre-commit'" \
|
||||
"Use when running the linter. Use pre-commit hooks instead of ad-hoc scripts."
|
||||
grammar_case fp-pull-request silent "" \
|
||||
grammar_case fp-pull-request suggests "routes to 'pull-request'" \
|
||||
"Use when opening changes. Invoke the pull-request template instead of writing one by hand."
|
||||
grammar_case fp-conventional silent "" \
|
||||
grammar_case fp-conventional suggests "routes to 'conventional-commits'" \
|
||||
"Use when writing history. Use conventional-commits formatting rather than free-form messages."
|
||||
grammar_case fp-prepush-backticked silent "" \
|
||||
grammar_case fp-prepush-backticked suggests "routes to 'pre-push'" \
|
||||
"Use when checking a branch. Do not use for local edits — run the \`pre-push\` hooks instead."
|
||||
|
||||
echo ""
|
||||
@@ -588,6 +621,309 @@ grammar_case lowercase-start suggests "routes to 'no-such-lower-skill'" \
|
||||
grammar_case backtick-start suggests "routes to 'no-such-tick-skill'" \
|
||||
"Use when doing the thing. Use sibling-skill for the main case. \`no-such-tick-skill\` is not for this — do not use it instead."
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2a. Route NOTATION always blocks, whatever token follows it
|
||||
# ---------------------------------------------------------------------------
|
||||
# FOLLOWER_OK is a closed whitelist of about eighty words. A target followed by
|
||||
# anything outside it was non-terminal, and `/name` reached _add() with
|
||||
# strict=None, so it fell to the follower test and lost the power to block —
|
||||
# contradicting the header's own promise that route notation "always blocks",
|
||||
# for the one form Claude Code actually uses. Combined with the old `continue`
|
||||
# in unresolved_targets(), `use /no-such-skill afterwards.` exited 0 with no
|
||||
# output at all: the gate failed OPEN on a word nobody had thought to enumerate.
|
||||
#
|
||||
# "afterwards" is the probe in every case below. It is ordinary English, it is
|
||||
# not in FOLLOWER_OK, and it is not going to be added to it.
|
||||
echo ""
|
||||
echo "--- route notation blocks even when the following token is outside FOLLOWER_OK ---"
|
||||
grammar_case notation-slash-unlisted errors "routes to 'no-such-slash-skill'" \
|
||||
"Use when doing the thing. Do not use for improvements — use /no-such-slash-skill afterwards."
|
||||
grammar_case notation-arrow-unlisted errors "routes to 'no-such-arrow-skill'" \
|
||||
"Use when doing the thing. Not the other thing -> no-such-arrow-skill afterwards."
|
||||
|
||||
echo ""
|
||||
echo "--- a target the follower rule cannot vouch for is REPORTED, never invisible ---"
|
||||
# The other half of the same defect, and the one that cost visibility rather
|
||||
# than enforcement: a PROSE-form target with an unlisted follower may not block
|
||||
# (that is what the follower rule is for) but it must still be named. Silence
|
||||
# here is the vacuous-green shape the whole script forbids itself.
|
||||
grammar_case follower-unlisted-bare suggests "routes to 'no-such-modifier-skill'" \
|
||||
"Use when doing the thing. Do not use for improvements — use no-such-modifier-skill afterwards."
|
||||
grammar_case follower-unlisted-backticked suggests "routes to 'no-such-ticked-skill'" \
|
||||
"Use when doing the thing. Do not use for improvements — use \`no-such-ticked-skill\` afterwards."
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2b. Capitalised abbreviations do not over-split a sentence
|
||||
# ---------------------------------------------------------------------------
|
||||
# SENTENCE_SPLIT was the one pattern in the resolver built without re.I, so its
|
||||
# five abbreviation lookbehinds only covered the lowercase spelling. `E.g.` and
|
||||
# `I.e.` — the SENTENCE-INITIAL spellings, which is exactly where an
|
||||
# abbreviation lands — matched none of them. The clause split at the
|
||||
# abbreviation, the corroborating target was stranded on the far side of the
|
||||
# cut, and a genuinely dangling target silently demoted from blocking ERROR to
|
||||
# SUGGESTION. The lowercase twin of each case below is `abbrev-split` above and
|
||||
# already passed, which is precisely why the gap survived.
|
||||
echo ""
|
||||
echo "--- a CAPITALISED abbreviation does not strand the corroborator ---"
|
||||
grammar_case abbrev-split-caps-eg errors "routes to 'no-such-caps-eg-skill'" \
|
||||
"Use when doing the thing. Do not use for improvements — use sibling-skill first, E.g. \"run the audit\", then use no-such-caps-eg-skill instead."
|
||||
grammar_case abbrev-split-caps-ie errors "routes to 'no-such-caps-ie-skill'" \
|
||||
"Use when doing the thing. Do not use for improvements — use sibling-skill first, I.e. \"run the audit\", then use no-such-caps-ie-skill instead."
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2c. A boundary clause naming a dotted filename (issue #110)
|
||||
# ---------------------------------------------------------------------------
|
||||
# `[^.;]` cannot cross the `.` in `AGENTS.md` or `.pre-commit-config.yaml`, so a
|
||||
# clause naming a dotted file between "Not" and the arrow was invisible to both
|
||||
# BOUNDARY_ARROW and ARROW_BOUNDARY. Two different failures came out of that:
|
||||
# with a backticked target the clause was merely MISDIAGNOSED as missing, and
|
||||
# with a BARE target it was never extracted at all, so the dangling check
|
||||
# silently did not run on it. Both directions are pinned.
|
||||
echo ""
|
||||
echo "--- a boundary clause naming a dotted filename is seen, and its target is checked ---"
|
||||
grammar_case dotted-bare-target errors "routes to 'no-such-dotted-skill'" \
|
||||
"Use when doing the thing. Not AGENTS.md -> no-such-dotted-skill."
|
||||
grammar_case dotted-clause-seen silent "" \
|
||||
"Use when doing the thing. Not .pre-commit-config.yaml -> sibling-skill."
|
||||
# The guard that makes the fix a fix and not a hole: a REAL sentence end still
|
||||
# ends the clause. A `.` followed by whitespace terminates it exactly as before,
|
||||
# so "Not applicable here." plus an arrow two sentences later is not a boundary
|
||||
# clause and is still reported as one missing.
|
||||
grammar_case dotted-sentence-end-guard suggests "has no boundary clause" \
|
||||
"Use when doing the thing. Not applicable here. Reproduce -> minimise."
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2d. "Present but unparsed" is a different finding from "missing"
|
||||
# ---------------------------------------------------------------------------
|
||||
# Issue #110's standing request. An arrow clause ALWAYS names a target, so one
|
||||
# that yields none is a parse failure and must say so — telling the author the
|
||||
# clause is missing sends them to add a second copy of a clause that is already
|
||||
# there. The live shape is a single-word target, which is deliberately not
|
||||
# matchable bare because `research`, `triage` and `forge` are all skill names
|
||||
# AND ordinary English.
|
||||
echo ""
|
||||
echo "--- an arrow clause that yields no target is reported as unparsed, not as missing ---"
|
||||
grammar_case arrow-single-word-target suggests "no target could be read" \
|
||||
"Use when doing the thing. Not the other thing -> forge."
|
||||
# Control, so the case above is not satisfied by a check that fires on every
|
||||
# arrow clause: the same clause with the target written in a shape the extractor
|
||||
# can see produces nothing at all.
|
||||
grammar_case arrow-single-word-marked silent "" \
|
||||
"Use when doing the thing. Not the other thing -> \`sibling-skill\`."
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2e. One arrow, one target (issue #107)
|
||||
# ---------------------------------------------------------------------------
|
||||
# Only the first target after an arrow is resolved: the conjunction continuation
|
||||
# is wired to the prose route verbs and never to arrows. So the second name in
|
||||
# `Not X -> a or b` was resolved by nothing and reported by nothing, and the
|
||||
# audit then printed "1 of 1 boundary target(s) resolve" on a clause naming two.
|
||||
# A typo in the second target shipped through a green gate.
|
||||
#
|
||||
# The fix rejects the shape rather than widening the extractor. The case below
|
||||
# is the exact failure: a bare `Not ... ->` sentence carries no BOUNDARY_MARKER,
|
||||
# so the backtick sweep does not run and the second target is genuinely
|
||||
# invisible to every other rule in the resolver.
|
||||
echo ""
|
||||
echo "--- an arrow clause naming two targets is rejected, so the unchecked one is visible ---"
|
||||
grammar_case multi-arrow-second-target suggests "names more than one target" \
|
||||
"Use when doing the thing. Not the other thing -> \`sibling-skill\` or \`no-such-second-target\`."
|
||||
grammar_case multi-arrow-comma suggests "names more than one target" \
|
||||
"Use when doing the thing. Not the other thing -> \`sibling-skill\`, \`no-such-comma-target\`."
|
||||
# Control: one arrow, one target — the convention the SUGGESTION is asking for —
|
||||
# stays silent. Without this the case above is satisfied by a check that fires
|
||||
# on every arrow clause in the corpus.
|
||||
grammar_case multi-arrow-control silent "" \
|
||||
"Use when doing the thing. Not the other thing -> \`sibling-skill\`."
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2f. A skill directory with no SKILL.md is not a skill
|
||||
# ---------------------------------------------------------------------------
|
||||
# _collect_package() added a name for every directory matching skills/*/, with
|
||||
# no check that anything was in it. A leftover empty directory — a deleted skill
|
||||
# whose directory survived, a scaffolding stub, an editor's stray mkdir — is
|
||||
# untracked by git, so it exists on the machine that made it and nowhere else.
|
||||
# The hook went green locally and red in a fresh clone: the same
|
||||
# install-dependence the deployed-tree rule exists to remove, arriving through a
|
||||
# different door. Both directions are asserted, because "never resolve" would
|
||||
# also satisfy the first half.
|
||||
echo ""
|
||||
echo "--- an empty skills/<name>/ directory does not make a routing target resolve ---"
|
||||
GHOST="$TMPDIR_T/ghost-dir"
|
||||
write_skill "$GHOST/plugins/p/.apm/skills/my-skill" my-skill \
|
||||
"Use when doing the thing. Do not use for the other thing — use /ghost-skill instead."
|
||||
mkdir -p "$GHOST/plugins/p/.apm/skills/ghost-skill"
|
||||
# NOT wrapped in a helper function: command substitution runs the body in a
|
||||
# subshell, so an exit status assigned inside one never reaches the caller —
|
||||
# under `set -u` the second read of it aborts the suite.
|
||||
set +e
|
||||
GHOST_OUT="$(bash "$HOOK" "$GHOST/plugins/p/.apm/skills/my-skill/SKILL.md" 2>&1)"
|
||||
GHOST_RC=$?
|
||||
set -e
|
||||
if [[ $GHOST_RC -ne 0 && "$GHOST_OUT" == *"routes to 'ghost-skill'"* ]]; then
|
||||
pass "a directory with no SKILL.md in it is not a resolvable name"
|
||||
else
|
||||
fail "an empty skills/ghost-skill/ directory resolved a routing target (exit $GHOST_RC): ${GHOST_OUT:-<empty>}"
|
||||
fi
|
||||
# The confirming half: drop a SKILL.md into the same directory and the identical
|
||||
# description resolves. Without this the rule could be implemented as "skills/
|
||||
# never contributes anything" and still pass above.
|
||||
write_skill "$GHOST/plugins/p/.apm/skills/ghost-skill" ghost-skill \
|
||||
"Use when doing the other thing. Do not use for anything else."
|
||||
set +e
|
||||
GHOST_OUT="$(bash "$HOOK" "$GHOST/plugins/p/.apm/skills/my-skill/SKILL.md" 2>&1)"
|
||||
GHOST_RC=$?
|
||||
set -e
|
||||
if [[ $GHOST_RC -eq 0 && -z "$GHOST_OUT" ]]; then
|
||||
pass "the same directory WITH a SKILL.md resolves, so the rule is 'no SKILL.md' and not 'never'"
|
||||
else
|
||||
fail "a populated skills/ghost-skill/ directory still did not resolve (exit $GHOST_RC): ${GHOST_OUT:-<empty>}"
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2g. The FREE-STANDING /name sweep, and its reach beyond a boundary sentence
|
||||
# ---------------------------------------------------------------------------
|
||||
# NOTATION_SLASH's own sweep in _extract_sentence() is what sees `/name` when no
|
||||
# route verb and no arrow precedes it. Nothing pinned it: every `/name` fixture
|
||||
# in this suite before these cases ALSO carried a route verb ("use
|
||||
# /no-such-slash-skill instead"), which ROUTE_ANY/ROUTE_MARKED extract on their
|
||||
# own, so deleting the sweep outright left the whole suite green. The eight
|
||||
# phrasings below carry no route verb in front of the target, so each of them is
|
||||
# invisible without the sweep — which is exactly the silence the sweep exists to
|
||||
# repair, and the shape the SUGGESTION tier's own remedy ("write it as `/name`
|
||||
# and it will be checked properly") used to teach an author to produce.
|
||||
echo ""
|
||||
echo "--- /name with no route verb in front of it is still extracted ---"
|
||||
grammar_case sweep-dash errors "routes to 'no-such-skill'" \
|
||||
"Use when doing the thing. Do not use for Y — /no-such-skill instead."
|
||||
grammar_case sweep-semicolon errors "routes to 'no-such-skill'" \
|
||||
"Use when doing the thing. Do not use for Y; /no-such-skill handles that."
|
||||
grammar_case sweep-paren errors "routes to 'no-such-skill'" \
|
||||
"Use when doing the thing. Do not use for Y (/no-such-skill covers it)."
|
||||
grammar_case sweep-possessive errors "routes to 'no-such-skill'" \
|
||||
"Use when doing the thing. Do not use for Y — that is /no-such-skill's job."
|
||||
grammar_case sweep-defer errors "routes to 'no-such-skill'" \
|
||||
"Use when doing the thing. Do not use for Y — defer to /no-such-skill."
|
||||
grammar_case sweep-terminal errors "routes to 'no-such-skill'" \
|
||||
"Use when doing the thing. Do not use for Y — /no-such-skill."
|
||||
# The arrow twin. `;` ends CLAUSE_BODY, so ARROW_BOUNDARY cannot reach across it
|
||||
# from `not`; only NOTATION_ARROW's own sweep sees this one.
|
||||
grammar_case sweep-arrow-after-semicolon errors "routes to 'no-such-skill'" \
|
||||
"Use when doing the thing. Do not use for Y; -> no-such-skill covers it."
|
||||
|
||||
# THE SWEEP IS NOT SCOPED TO A BOUNDARY SENTENCE, and this is the case that
|
||||
# proves it. Extraction is per-sentence (corroboration is scoped to one
|
||||
# sentence), so gating the `/name` sweep on the sentence carrying a
|
||||
# BOUNDARY_MARKER meant a route written one sentence AFTER the boundary clause
|
||||
# was never looked at: exit 0, no ERROR, no SUGGESTION, not even the name. That
|
||||
# contradicts ADR-0020's amendment and docs/spec/gates.md, which both promise
|
||||
# `/name` blocks unconditionally, for any name.
|
||||
#
|
||||
# The first sentence's `/sibling-skill` is deliberate: it resolves, so the
|
||||
# fixture is not "the gate fires on any slash it sees" — it fires on the one
|
||||
# that dangles, in the sentence that carries no boundary marker at all.
|
||||
echo ""
|
||||
echo "--- /name is checked in a sentence that carries no boundary marker ---"
|
||||
grammar_case sweep-outside-boundary errors "routes to 'no-such-skill'" \
|
||||
"Use for X. Do not use for Z — use /sibling-skill instead. For W, /no-such-skill is the right entry point."
|
||||
# Control, so the case above is not satisfied by a gate that fires on every
|
||||
# unresolvable-looking token in a non-boundary sentence: the same shape with a
|
||||
# name that RESOLVES stays silent.
|
||||
grammar_case sweep-outside-boundary-control silent "" \
|
||||
"Use for X. Do not use for Z — use /sibling-skill instead. For W, /sibling-skill is the right entry point."
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2h. A slash PATH is not a route (the trailing guard, and its backtracking)
|
||||
# ---------------------------------------------------------------------------
|
||||
# There was no path or URL fixture anywhere in this suite, and the guard was
|
||||
# defeated by ordinary regex backtracking. `/(NAME_ANY)\b(?!/|\.\S)` looks like
|
||||
# it refuses a path, and does not: when the lookahead rejects the FULL segment
|
||||
# the engine backtracks to a shorter hyphen-terminated prefix, `\b` still holds
|
||||
# after a hyphen, and the phantom is reported as a hard BLOCKING ERROR naming a
|
||||
# skill nobody wrote:
|
||||
# /opt-tools/bin/thing -> ERROR: routes to 'opt'
|
||||
# /api-docs/v2.md -> ERROR: routes to 'api' AND to 'api-docs'
|
||||
# /no-such-skill.md -> ERROR: routes to 'no-such'
|
||||
# `(?![\w-])` is the guard that actually holds, because it forbids the shortened
|
||||
# prefix instead of merely disliking the full one. MARKED_TARGET carries it too:
|
||||
# that pattern had NO trailing lookahead at all, which is where the second
|
||||
# 'api-docs' error above came from.
|
||||
#
|
||||
# These are `silent`, not `suggests`. A path is not a routing target at any
|
||||
# tier — reporting one would be the same false positive one notch quieter, on
|
||||
# the skills most likely to name a path in a boundary clause.
|
||||
echo ""
|
||||
echo "--- a slash PATH in a boundary sentence is not a routing target ---"
|
||||
grammar_case path-absolute silent "" \
|
||||
"Use when doing the thing. Do not use for Y; the config lives at /opt-tools/bin/thing."
|
||||
grammar_case path-dotted-file silent "" \
|
||||
"Use when doing the thing. Do not use for Y — see /api-docs/v2.md for the schema."
|
||||
grammar_case path-dotted-backticked silent "" \
|
||||
"Use when doing the thing. Do not use for Y — see \`/api-docs/v2.md\` for the schema."
|
||||
grammar_case path-md-suffix silent "" \
|
||||
"Use when doing the thing. Do not use for Y — the file /no-such-skill.md documents it."
|
||||
# The two suppressions that were already working and must keep working: a URL
|
||||
# (the `/` is preceded by a word character or by another `/`) and a relative
|
||||
# references/ pointer. Asserted explicitly because the guard above is a change to
|
||||
# the same lookarounds, and a fix that traded one silence for another would look
|
||||
# identical from the corpus.
|
||||
grammar_case path-url silent "" \
|
||||
"Use when doing the thing. Do not use for Y — see https://example.com/no-such-skill for details."
|
||||
grammar_case path-relative silent "" \
|
||||
"Use when doing the thing. Do not use for Y — see references/no-such-skill.md for details."
|
||||
# The other direction, which is what stops the guard from becoming a hole: a
|
||||
# name whose only follower is the SENTENCE-ENDING dot is still a route. A
|
||||
# closing `.` is not followed by a non-space, so `(?!\.\S)` does not reject it.
|
||||
# Without these, "refuse every /name near a dot or a slash" would pass every
|
||||
# case above and silently delete the notation tier.
|
||||
echo ""
|
||||
echo "--- the path guard does not swallow a /name at a real sentence end ---"
|
||||
grammar_case path-guard-sentence-end errors "routes to 'no-such-skill'" \
|
||||
"Use when doing the thing. Do not use for Y — defer to /no-such-skill."
|
||||
grammar_case path-guard-mid-sentence errors "routes to 'no-such-skill'" \
|
||||
"Use when doing the thing. Do not use for Y — use /no-such-skill for that instead."
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2i. A DIRECTORY named <something>.md is not an agent
|
||||
# ---------------------------------------------------------------------------
|
||||
# The skills branch of _collect_package() tests for a SKILL.md; the agents
|
||||
# branch takes every `*.md` glob hit on trust, and glob does not distinguish a
|
||||
# file from a directory. A leftover directory named `ghost-agent.md` — a botched
|
||||
# `mkdir`, an editor's stray save, a half-deleted agent — is untracked by git, so
|
||||
# it exists on the machine that made it and nowhere else, and it resolved a
|
||||
# routing target there and dangled everywhere else. That is exactly the
|
||||
# install-dependence fixture 2f pins one directory over, and the isfile() guard
|
||||
# closing it had no test at all: deleting it left every suite green.
|
||||
echo ""
|
||||
echo "--- an agents/<name>.md DIRECTORY does not make a routing target resolve ---"
|
||||
GHOST_AGENT="$TMPDIR_T/ghost-agent-dir"
|
||||
write_skill "$GHOST_AGENT/plugins/p/.apm/skills/my-skill" my-skill \
|
||||
"Use when doing the thing. Do not use for the other thing — use /ghost-agent instead."
|
||||
mkdir -p "$GHOST_AGENT/plugins/p/.apm/agents/ghost-agent.md"
|
||||
set +e
|
||||
GHOST_AGENT_OUT="$(bash "$HOOK" "$GHOST_AGENT/plugins/p/.apm/skills/my-skill/SKILL.md" 2>&1)"
|
||||
GHOST_AGENT_RC=$?
|
||||
set -e
|
||||
if [[ $GHOST_AGENT_RC -ne 0 && "$GHOST_AGENT_OUT" == *"routes to 'ghost-agent'"* ]]; then
|
||||
pass "a DIRECTORY named ghost-agent.md is not a resolvable agent name"
|
||||
else
|
||||
fail "a directory named agents/ghost-agent.md resolved a routing target (exit $GHOST_AGENT_RC): ${GHOST_AGENT_OUT:-<empty>}"
|
||||
fi
|
||||
# The confirming half, exactly as in 2f: replace the directory with a real file
|
||||
# and the identical description resolves. Without it the rule could be
|
||||
# implemented as "agents/ never contributes anything" and still pass above.
|
||||
rmdir "$GHOST_AGENT/plugins/p/.apm/agents/ghost-agent.md"
|
||||
: > "$GHOST_AGENT/plugins/p/.apm/agents/ghost-agent.md"
|
||||
set +e
|
||||
GHOST_AGENT_OUT="$(bash "$HOOK" "$GHOST_AGENT/plugins/p/.apm/skills/my-skill/SKILL.md" 2>&1)"
|
||||
GHOST_AGENT_RC=$?
|
||||
set -e
|
||||
if [[ $GHOST_AGENT_RC -eq 0 && -z "$GHOST_AGENT_OUT" ]]; then
|
||||
pass "the same path as a FILE resolves, so the rule is 'not a file' and not 'never'"
|
||||
else
|
||||
fail "a real agents/ghost-agent.md file still did not resolve (exit $GHOST_AGENT_RC): ${GHOST_AGENT_OUT:-<empty>}"
|
||||
fi
|
||||
|
||||
# And the confirming half of the grammar rule: a compound-modifier target is
|
||||
# CONFIRM-ONLY, not ignored. When the name does exist it still counts as a route
|
||||
# — the rule suppresses the ERROR, it does not delete the target.
|
||||
|
||||
Reference in New Issue
Block a user