00c1e6b (the ADR-0020 retrofit of diagnose) moved a bullet referencing
scripts/hitl-loop.template.sh out of SKILL.md and into the new
references/feedback-loops.md, and in the move flipped the correct
skill-root-relative path into an incorrect parent-relative one
(../scripts/...) -- despite that commit's own message claiming to fix
"a script path that did not resolve." References in this skill are
written relative to the skill root regardless of which file carries
them, matching the convention used throughout SKILL.md.
Found via an independent post-closure audit of issue #99; validated
clean via skill-audit afterward.
Refs #99
An independent audit of the ADR-0020 retrofit (issue #99) found that
git-submodules, git-worktrees, and gitea-files each collapsed their
description length correctly during retrofit but left the capability
clause as a verb enumeration (e.g. "Create, list, lock, move, remove,
prune, or repair") instead of ADR-0020's required single clause. The
deterministic char-count gate can't catch this — it's a qualitative
rubric violation the retrofit commits' own messages never claimed to
address, only measurable length/word-count fixes.
Validated clean via skill-audit and skill-size-check after the fix;
boundary clauses and routing targets left untouched.
Refs #99
Sets `disable-model-invocation: true`, so the host withholds caveman from
the model-visible skill listing. It stops paying preload tax and can only
be reached by typing /caveman.
The reason is not the 287 characters. caveman's description was almost
entirely a trigger list -- "caveman mode", "talk like caveman", "less
tokens", "be brief" -- and "be brief" is a false-positive magnet: a user
asking for brevity wants short answers, not dropped articles and
`Respond terse like smart caveman`. Removing the skill from the router
deletes the bad trigger. User's call, made explicitly.
Safe to flag because the flag also hard-blocks the Skill tool, so any
inbound route from another skill would break. Re-checked all 39
descriptions and bodies after four waves of retrofit rewrites: every
mention of caveman is documentation, research notes or the lockfile.
Nothing routes to it.
The description is rewritten as human-facing text, since it is no longer
a routing surface -- it now says how to turn the mode on and off rather
than listing phrases for a reader that can no longer see it.
The two remaining SUGGESTIONs are #108: the boundary-clause check fires on
hand-invoked skills, which ADR-0020 contractually exempts. Advisory, and
not to be "fixed" in the skill.
Preload tax 10,002 -> 9,732 chars across 37 model-visible skills.
Refs #99
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
915eb09 rewrote the bare-arrow carve-out comment in scripts/skill-size-check.sh
without pasting the block over the two other copies, so the resolver stood at
764 lines in the hook and 755 in both audit validators.
tests/test-adr0020-contract.sh exists to catch exactly this and did -- it was
the regression behind that suite's failure, and I reported the suite green
after 915eb09 without re-running it.
No behaviour changes: the drift was comment-only. Restoring identity keeps the
invariant the test enforces, which matters because the three copies are the
only thing making the hook and the two validators agree on what a boundary
target is.
Refs #99
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
body-discipline.md and contract.md both cite apm-workflow by hard number
as the reference dispatch shape, and instruct authors to calibrate against
its body word count. The retrofit in 1e4aab5 moved every one of those
figures: body 421 -> 237, whole-file 554 -> 304, references 3,006 ->
3,222. Measured, not estimated.
The quoted closing line was stale too -- it now carries a continuation
clause, so it is quoted with an ellipsis rather than as a full sentence.
These are positive exemplars in live guidance, so they are refreshed
rather than pinned. That is the opposite treatment from the git-commits
negative example in the same file, which is pinned to 5e23250 precisely
so it keeps describing the pre-retrofit state. ADR-0020 carries the same
figures and is deliberately left alone: it self-pins every citation to
base commit f9b919d, and refreshing it would destroy the record of what
the decision was taken against.
Refs #99
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
Description 514 -> 213 chars, Gotchas 5 entries/47% -> 2 entries/17%.
Body 350 -> 397 words: three Gotchas fold into the steps they gate, and
the repairs below add back what the fold dropped.
Cuts the second trigger register, the runtime enumeration (still named in
the body and README) and the enumeration inside the boundary clause.
Fixes four defects the first pass introduced:
- The mirror bullet claimed the piped one-liner "ignores" VERSION and
GITHUB_URL. The installer reads both from the environment and its own
usage header documents VERSION working through the pipe. The real
constraint is that an air-gapped host cannot reach aka.ms, so the
script must be on disk. Also corrects the variable names --
APM_RELEASE_BASE_URL is the mirror base, GITHUB_URL is the Enterprise
host.
- "If apm --version already answers, skip to Step 2" was unconditional on
intent, so a pin or upgrade request routed past the only pin
instruction in the skill. Now gated on intent.
- The PEP 668 rule was demoted to post-failure recovery, leaving a
routing rule that sent a Debian box into a command that hard-fails.
The prohibition is back on the pip bullet, before the choice.
- The apm-is-not-a-runtime Gotcha lost its operative clause. The two
step headings cited as carrying it already existed pre-retrofit, so
nothing had replaced it and nothing stated when Step 2 is required.
Refs #99
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
Description 648 -> 387 chars, body 1093 -> 541 words. This was the last
body FAIL in the 39-skill corpus.
The body was not trimmed to fit. forge routes four artifact types that a
single invocation classifies between, so the contract requires a dispatch
table plus the gates common to every route, with each route self-contained
in references/. Adds references/author-routes.md (skill and agent),
references/apm-routes.md (plugin and marketplace entry) and
references/version-bump.md. Skill and agent share one file: they differ on
one axis only, which audit skill verifies the result.
Fixes three defects the first pass introduced or relocated:
- references/apm-routes.md claimed `apm audit` "already runs inside
apm-workflow's own flow" and told the agent to confirm it ran clean.
apm-workflow dispatches audit as its own row; the configure and
marketplace rows never reach it. That was the only completion check
these routes had, and it could never be satisfied. Replaced with a
manual read-back the agent performs itself.
- "Read only the reference file" forbade the multi-artifact case the same
body documents two lines later, and ADR-0011 records eight artifacts
authored in one pass.
- The announce gate became a closing gate, reachable only after the
invocation it was meant to precede. Moved to the end of Step 2.
Also restores the artifact enumeration to the plugin row, normalises to
bare unnamespaced skill names per AGENTS.md, adds a dispatch fallback for
artifacts matching no row, and corrects three provenance entries -- one
asserted a contribution that did not happen.
Refs #99
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
Description 817 -> 324 chars, body 421 -> 237 words, Gotchas 6 -> 2.
The five capability clauses, the second trigger register and the prose
boundary form go; one trigger clause, the indirect trigger and one
boundary clause remain. Four of six Gotchas move into the flow file that
every branch needing them already loads.
Two stay in the always-loaded body because a dispatch body must carry the
gates common to every branch, not just the dispatch table: the MCP secret
indirection rule, and the `apm experimental enable registries`
precondition. The first pass moved registries into references/configure.md
alone, which stranded it -- references/compile.md documents publishing to a
registry and references/install.md resolves dependencies through one, and
neither points at configure.md. Declaring a registry without the
precondition is a silent no-op, so the failure had no signal.
Also drops an unsourced claim the compression pass introduced (that apm
checks `type:` going forward -- no source supports it), corrects the MCP
rationale to install *or* runtime per configuration.md:98, and repoints
two apm-orchestrate back-references that pointed at body Gotchas which had
moved.
Refs #99
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
body-discipline.md required every reference load to use the literal
'If X, read references/file.md' form and called anything else a generic
pointer. ADR-0020's own cited dispatch exemplar, apm-workflow, uses a
bare table plus one closing line, so an author could not satisfy both --
and the rule reliably produced duplication in exactly the bodies the
contract exists to keep short.
Resolves#109 with its option 1: a table row already pairs a condition
with a target, so where a body dispatches, the table is the wiring. The
literal form is what a body needs when it loads a reference without a
table.
Two corrections to the issue as filed. There is no Vale conflict --
PaddingPhrase.yml only matches 'see references/ for more info' and never
fired on the exemplar, so this is a one-file prose fix and no rule
changes. And gitea-workflow carried the predicted duplication: a
three-row table restated underneath as three conditionals. Removed, body
227 -> 148 words.
Closes#109
Description 654 -> 294 chars, Gotchas 36% -> 19%. Body 698 -> 642 words:
up from the first pass, because a clean-context audit found four defects
whose fixes are net-additive text.
The suppression-markup warning covered only one of the two paths that
write it -- the list is case-based, so a recurring false positive goes
straight to step 3 and never read step 2's warning. Hoisted above both.
The CI-failure trigger, which the description advertises, had no path to
the file holding its answer: the negative diagnosis 'if the alerts are
warnings, Vale is not what failed the build' survived only in
troubleshooting.md, which no CI-entered invocation loads. An agent would
confidently prescribe --no-exit for a failure Vale never caused.
The description had lost every prose-domain word -- no 'prose', no
'linter' -- while vale-config kept all of them, so 'check prose style'
routed to the wrong skill of the pair.
Accepts two soft SUGGESTIONs rather than dropping restored content;
neither fails the gate.
Refs #99
Description 657 -> 244 chars, body 504 -> 342 words, Gotchas 50% -> 24%.
The 50% was the worst ratio in the corpus and a real inverted body, not
the denominator artefact the ratio usually flags: half the body was a
Gotchas section doing duty as reference material.
A clean-context audit caught the split leaving a false statement behind.
Gotcha 1's kernel lost the qualifier that only package styles need
fetching, so it asserted that any style vale sync has not fetched fails
-- contradicting the same file twice, since the built-in Vale style and
any committed custom style are never fetched. An agent adding a custom
style would have added a spurious Packages entry and broken vale sync
outright. The qualifier is restored in the body rather than behind a
fourth reference pointer.
Also corrects the moved fixture's framing, which tabulated a control row
under a heading claiming it came from a multi-line fixture.
Refs #99
Description 833 -> 239 chars, body 370 -> 387 words, Gotchas 41% -> 20%.
The file-type enumeration moves to a new references/provider-matrix.md;
the composition note was already in README.md.
Three defects a clean-context audit found, all fixed:
The 'never edits AGENTS.md' prohibition had become a justification clause
on the false branch of a conditional, so the common path never read a
sentence binding it. That matters because the bundled validator's own
remediation text tells the agent to move content into AGENTS.md, so a
size FAIL actively invited the prohibited edit. Restored as a standing
imperative, plus a counter at the step where the trap fires.
A Gotcha asserted that validate-adapter.sh fails without
--no-import-syntax. The flag is a no-op -- both branches reduce to the
same expression. Reverted to an instruction; the script defect is #115.
The boundary clauses used pronouns to dodge the #110 regex, and 'Not
auditing it' resolved to CLAUDE.md as readily as to AGENTS.md -- routing
'audit my CLAUDE.md' to a skill whose own description declines it.
Refs #99
Description 944 -> 322 chars, Gotchas 36% -> 22%. The composition note
moves to README.md.
Restores the hand-edit trigger, which a clean-context audit found had no
other caller: agentsmd-author owns the post-authoring invocation, but a
hand-edit has no author skill in the loop, so nothing invoked the audit
at all. It survived only in README.md, which neither the router nor the
invoked agent loads. That is the path on which a human pastes a
credential into AGENTS.md.
The first pass dropped it against a measured budget of '~9 spare chars'.
The real cost was ~49, and 250 is the SUGGESTION tier, not a ceiling --
the gate fails at 400. Ships at 322 with one advisory line.
Names the three audit dimensions in the capability clause, recovering
routing for 'does my AGENTS.md leak credentials', and qualifies the
'is this AGENTS.md safe to commit' phrasing, whose pronoun had no
antecedent inside the quoted string.
Refs #99
Description 960 -> 244 chars, body 470 -> 452 words, Gotchas 36% -> 22%.
Both composition notes move to README.md, which already carried them.
Four of five Gotchas were paraphrases of the step below them and were
deleted with their force folded back into that step. A clean-context
audit overturned the fifth deletion: the provider-file prohibition was
strictly broader than Step 4, so it was never a paraphrase, and Step 4's
'don't rewrite it yourself' is attached to the if-duplicates branch. With
Write and Edit granted, a provider file that was merely stale had nothing
forbidding an edit. Restored as an unconditional Gotcha, read before any
step writes.
Also restores a concrete indirect trigger. The retrofit had replaced two
with the meta-statement 'even when they don't name the file', which
claims an indirect trigger exists rather than being one -- and users
asking to document a repo for AI tools have no reason to know the
filename.
Refs #99
Body 1126 -> 808 words, clearing the FAIL tier, and description 290 ->
220 chars. Phase 1's depth moves to references/feedback-loops.md; the
six-phase spine stays in the body, since a linear procedure is not a
dispatch case.
The description rewrite was not originally in scope, which was an error:
adding a mandatory boundary clause to a 290-char description cannot land
under 400. The dropped capability chain was also inaccurate -- it named
'minimise' as a phase that does not exist while omitting the one phase
the body calls 'This is the skill'.
A clean-context audit found no text lost but three reachability defects,
all fixed: content stranded behind an inverted trigger, Phase 2's
reproduction-rate threshold defined only in a file that path never
loaded, and a script path that did not resolve from the file carrying it.
The two reference files are merged into one, since the split is what
created the first two.
Refs #99
Description 426 -> 286 chars, with a boundary clause added. The body was
already compliant at 467 words and is untouched.
A clean-context audit caught the first pass trading away the LOGIC
branch's routing vocabulary for characters it did not need to save: both
'data model' and 'business logic' had gone, though LOGIC.md defines its
own scope with exactly those words. Restored, so 'does this data model
feel right?' routes here again.
Accepts 286 over the 250 target -- the hard tier is 400, and the
alternative was leaving half the dispatch reachable by one phrase.
Leaves LOGIC.md and UI.md at the skill root; moving them into references/
is tracked as #114.
Refs #99
Description 583 -> 231 chars and body 854 -> 519 words. Deletes the
neuledge-context boundary clause outright: commit 6146120 deleted that
skill and no skill has owned MCP-server installation since. That was the
last dangling routing target in the corpus.
Removes META.md, which file-structure.md:20 forbids at a skill root. Its
when: field duplicated the description and its references: entry pointed
at .agents/skills/context7-mcp/SKILL.md, which does not exist.
Restores two rules a clean-context audit found had lost their force: the
starting-URLs branch in step 3, which the retrofit had reduced to a
condition with no behaviour, and the references/file-format.md pointer at
step 6. The second matters downstream -- validate-provenance.sh parses
sources.md with anchored regexes and check 8 short-circuits silently when
the Status field is absent, so a sources.md written from step 6 alone
broke the provenance chain with no error anywhere.
Rewrites steps 4-5 as serial WebFetch reads. They mandated spawning
subagents that allowed-tools never granted; no tool was added because the
name differs across the three compile targets. Tracked as #116.
Updates the two test pins and the eval case that asserted the dead route.
Refs #99
The body-discipline rubric cited git-commits as it stood before the ADR-0020
retrofit -- twelve Gotchas, 387/1102 words, line numbers :31-:52. Every
figure was correct for that version and none survives in the current file,
so the example is now anchored to commit 5e23250 and marked not to be
refreshed against HEAD.
More than staleness: row four called the secrets Gotcha a paraphrase FAIL
because step 2 restated it. Wave 2 followed that reasoning, deleted the
always-loaded copy, and left the amend branch able to commit a credential
unchecked -- dispatch loads exactly one flow file. The paraphrase rule now
carries its missing precondition: delete a restating Gotcha only when the
surviving copy is reachable from every branch that needs it, and relocate
a multi-branch safety gate into the body rather than dropping it.
Description 475 -> 213 chars, body 680 -> 212 words. Create and modify
become self-contained flow files behind a dispatch table, since the two are
mutually exclusive on whether the config already exists.
Passed its clean-context audit with no must-fix findings.
Description 477 -> 211 chars, body 736 -> 367 words. Install, autoupdate,
and clean become flow files behind the Route table.
The audit found no route for 'hooks aren't running': the only pointer to
failure-patterns.md sat inside the failure path, but when hooks never fire
the manual run succeeds, so the request fell to the ambiguity default and
was masked. Restores the disclosure that install -f is not reversible by
uninstall.
Description 450 -> 266 chars, body 1044 -> 462 words. The bisect procedure
moves to references/bisect.md.
The boundary clause read 'not writing or rewriting commits', which
disclaimed the cherry-pick and revert this skill's own Step 3 executes; it
now excludes authoring and rebasing only. Adds 'backport' so cherry-pick is
reachable by natural language at all, accepting 266 chars against a 250
soft target and a 400 ceiling.
Description 480 -> 248 chars, body 1011 -> 347 words. The single
submodules.md splits into setup-and-update, urls-and-config, and removal.
Restores three regressions the first pass introduced: 'repointing' as the
trigger for the URL branch, which had none while the boundary clause
steered those queries to git-remotes; clone and absorbgitdirs in the output
enum, which dispatch still routed to; and status --cached, the flag that
makes the pre-commit pointer gate verifiable.
Description 566 -> 249 chars, body 644 -> 398 words, Gotchas 12 -> 2. The
eight organisational hard rules move to references/hard-rules.md.
Its load trigger enumerates operations rather than rule topics: the first
draft keyed on 'commit message form', which left the atomicity and
working-state rules unreachable when a caller supplied a conventional
message. Also promotes the destructive-op confirmation ahead of the
orchestrator invocation, which it previously followed.
Description 582 -> 237 chars, body 1217 -> 290 words. The single remotes.md
splits into config, fetch, push, and pull flow files.
Restores the confirm: true token to the force-push gate -- it is the git
plugin's cross-skill contract, gated on by git-orchestrate and git-branches.
Moves push.md's worked example off main, which the skill's own Step 1
refuses, and restores the never-bare---force directive.
Description 592 -> 248 chars, body 756 -> 515 words, Gotchas 8 -> 4.
The audit found the dispatch table had no row for a worktree on an
existing local branch, so that request fell to the adjacent -B row, which
resets the branch to HEAD and discards its commits. Non-destructive create
is now the first row and -B names its own destructiveness. Adds the missing
lock/unlock row and repair's run-from constraint.
Description 612 -> 273 chars, body 1124 -> 457 words. Branch patterns,
operations, merging, comparison, and the orchestrator contract move to
references/.
Corrects rebase routing in four places: this skill sent rebase to
git-history, which carries no rebase content and disclaims it. Rebase is
git-commits'; cherry-pick and revert stay git-history's. Drops a Step 3
gate on a rebase flow this skill does not have.
Description 724 -> 214 chars, body 1102 -> 343 words, Gotchas 12 -> 3.
Create, rewrite, and cherry-pick flows move to self-contained references/
files behind a dispatch table.
The audit caught that moving the secret scan into the create flow left the
amend/squash path with no check in its loaded context; it is now a gate
common to every flow. Also re-homes the interactive-rebase reflog warning
git-history dropped, since this skill owns rebase.
Generated output, not authored content: scripts/sync-plugin-content.sh --all.
Claude Code has no .apm/ awareness, so this compiled mirror must track .apm/ or
the check-plugin-content-sync pre-push hook reports drift.
Deferred to a single commit at the end of the wave on purpose. sync_dir runs
rm -rf before every copy, so running it while seven agents were editing the
same plugin would have raced them; agents were told not to sync for that reason.
Refs #99
Description 1012 -> 347 chars, body 582 -> 170 words, Gotchas 3 entries -> 1 at
22.9% of body. Clears the description FAIL and all four Vale CompositionNote
errors -- the last carriers in the corpus, so that rule now fires nowhere.
Cut the 'human-facing entry point and router' architecture note, the /gitea
migration history and the six-skill composition list; all were already in the
README or the routing table.
Split three mutually exclusive flows into a dispatch table keyed on invocation
shape, each branch self-contained in references/: status-checkin.md,
number-resolution.md, skill-index.md. Report stays in the body as the gate
common to every branch; each branch's own format moved to its file. The old
Step 1-4 numbering presented three alternatives as a sequence.
The description grew from an intermediate 283 chars on purpose: that draft had
dropped flow 3's trigger entirely, leaving the domain-routing index -- a third
of the skill -- reachable only through a tail clause whose grammatical subject
was the request rather than the skill. Both gates were green over that.
Boundary clauses are one arrow per target, so both resolve (#107: the resolver
extracts only the first target per clause and reports 1 of 1 on a clause naming
two). The local-git exclusion keeps its wording but drops the route to
git-workflow, which would not resolve in a gitea-only install.
Known residual: the dispatch conditions are stated twice, as a table and as
literal conditionals. That is #109 -- body-discipline.md mandates the literal
form while the ADR's cited exemplar, apm-workflow, uses a bare table plus one
summary line. Fixing it here would settle that contradiction in a skill rather
than in the spec, so it rides with #109.
Refs #99, #107, #109
Description 835 -> 214 chars, body 669 -> 426 words, Gotchas 8 entries/63% of
body -> 3/20.4%. Clears the description FAIL, all three Vale CompositionNote
errors and both Gotchas suggestions. 63% was the worst Gotchas ratio in the
corpus.
Cut the composition sentence to README -- it changes no routing decision and an
agent picks this skill because the user asked about labels, not because two
other skills call it. Cut the capability enumeration; 'list, create, edit,
delete' decompose 'reading or writing' and add no trigger.
Boundary clauses are now one arrow per target. The resolver extracts only the
first name per arrow clause, so the previous '-> gitea-issues / gitea-prs' left
gitea-prs neither dangling nor checked while validate.sh reported 1 of 1. Now
2 of 2.
Makes org-scoped label resolution executable. The org label pool was reachable
in principle -- four *_org_label* methods, and a claim to own name-to-ID
resolution -- but list_org_labels takes org, and Step 1 derived only owner and
repo, so both resolution procedures stalled at the fallback. Fixed once at the
identity step rather than per-procedure. get_user_orgs is outside allowed-tools,
so the failing call is the discriminator: a failure means the owner is a user
account with no org pool, which is an answer, not an error.
Corrects a Gotcha that was false for create_repo_label/create_org_label and
collided with the literal tool name label_write. Same false claim removed from
README.
Refs #99
Description 827 -> 182 chars, body 902 -> 584 words, Gotchas 7 entries/43% of
body -> 4/23.1%. Clears both size FAILs, the dangling-target FAIL and the Vale
CompositionNote error.
The dangling 'gitea-labels' target is gone with the composition sentence that
carried it -- a YAML fold artifact, not a typo: the '>'-folded scalar joined
'gitea-labels-' and 'milestones' across a line break, leaving the name terminal
and danglable. Both boundary names now sit whole on one source line each, and
both resolve.
Cut the second trigger register, the seven-verb capability enumeration, the
issue_write implementation detail and a gitea-branches boundary that defended
nothing. Two Gotchas deleted as spec restatement carried in references/, one as
a paraphrase of the step below it.
Closes a capability hole rather than papering over it: gitea-labels-milestones
routes label application here and has no issue_write, but no dispatch row
existed for add/replace/remove/clear_labels or get_labels. Both rows added.
The label ID/name Gotcha is now stated per method -- issue_write takes IDs,
list_issues and search_issues filter by name, issue_read 'get' returns names
but 'get_labels' returns full objects with IDs.
Drops a stale quotation of gitea-labels-milestones' description from
references/enrichments.md; that string went with its composition note.
Refs #99
The reference files were last verified against v1.3.0 -- references/sources.md
still said so. PR #106 re-verified the write side only, so three defects had
accumulated on the read/review side. All three reproduced against the deployed
server before being fixed; get_gitea_mcp_server_version reports v1.7.0.
- reviews.md forbade review_comments on the "get" response and directed callers
to review_scomments, which does not exist. The upstream slim.go typo was
corrected; a live pull_request_read on PR #106 returns "review_comments":1 and
no review_scomments key. review_comments is an integer count, not comment
objects -- distinct from the get_review_comments method. Also fixed in
pull-requests.md's response-shape list.
- pull_request_review_write grants seven methods; only four were documented.
reply_comment, resolve_thread, unresolve_thread and the comment_id parameter
had zero mentions anywhere in the skill. Documented from the schema, in a
Comment threads section kept outside the numbered review state machine --
they are not lifecycle states.
- review_id was documented as required for get_review_comments. It is optional;
omitting it lists every inline comment on the PR. Confirmed behaviourally:
get_review without it errors, get_review_comments without it returns [].
sources.md now records v1.7.0 as the last-verified version, so the next reader
knows what these files were checked against.
Refs #99
Description 709 -> 161 chars, body 683 -> 353 words, Gotchas 8 entries/56% of
body -> 2/24.9%. Clears the description FAIL and both Vale CompositionNote
errors.
Fixes the three stale claims recorded on issue #99, all re-verified against the
deployed gitea-mcp schema during review:
- The description no longer advertises 'reviewers' as an update capability.
editPullRequestFn never reads reviewers or team_reviewers; only
add_reviewers/remove_reviewers do.
- milestone is now marked honoured on "update" only, in the Gotcha, the body
and the dispatch table's create row. On "create" the server discards it and
omits the key from the response, so the drop is indistinguishable from never
passing it -- and labels DOES apply on create, so labels landing is no
evidence the milestone did. The old text told callers to resolve a milestone
before any write, wasting the lookup on create.
- The superseded un-draft workaround is gone. "update" with draft:false and no
title makes the server strip the prefix itself, including [WIP],
case-insensitively -- carried by references/pull-requests.md, corrected in
PR #106.
The 22-row tool/method table becomes a 5-row dispatch table; all 20 operations
it named remain reachable, including update_branch and the reviewer methods.
Refs #99
Description 787 -> 263 chars, body 922 -> 302 words, Gotchas 9 entries/69% of
body -> 3/24.8%. Clears both size FAILs and both Gotchas suggestions.
Deleted the second trigger register outright -- ~300 chars re-quoting the same
six verbs as user phrasings, which ADR-0020 names this skill for specifically.
Split the body on the read/write boundary: one invocation cannot both read and
write, so a dispatch table is mandatory. Six operations collapse into two flow
files rather than six -- create/update/delete share one tool pair and one
SHA-first lifecycle whose preamble would otherwise be triplicated, and the three
read tools share ref selection plus a 'neither listing is a SHA source'
comparison that only exists between them.
references/examples.md removed; all eight of its content blocks and all nine
named parameters carry into references/writing.md, verified against git HEAD.
Two deltas are corrections: the repo tree is now ruled out as a SHA source, and
reusing a SHA captured earlier in the conversation is now forbidden.
Four Gotchas relocated to the flow file that needs them; two promoted to gates
(SHA-as-concurrency-token opens writing.md; owner/repo became ## Inputs).
Refs #99
Description 688 -> 282 chars, body 435 -> 293 words, Gotchas 5 entries/54% of
body -> 3/23.5%. Clears the description FAIL and the Gotchas suggestion.
Cut the second trigger register (six re-quoted user phrasings) and the capability
enumeration; both moved to a new Boundaries section in the skill's own README.
Kept all three boundary clauses -- git-branches, git-history and gitea-prs each
defend a real activation steal, and gitea-prs is now the only guard on the
branch/PR collision in either direction since gitea-prs's own retrofit narrowed
its boundary to issues. Written as one arrow per target: the resolver extracts
only the first name per arrow clause, so conjoined targets go unchecked.
Two Gotchas deleted -- one paraphrased the step below it (its non-obvious half,
the get_me/list_my_repos token-scope block, was folded into that step), the other
is carried in full by references/branches.md:40-52.
Repoint two reference pointers the rename broke: branches.md and commits.md named
Gotchas by titles this retrofit changed. Now named by stable descriptors.
Refs #99
Description 500 -> 211 chars, body 676 -> 462 words, Gotchas 5 entries/41% of
body -> 3/21%. Clears the description FAIL and both Gotchas suggestions.
Cut the second trigger register (the re-quoted user phrasings), the doubled
capability enumeration across releases and tags, and the gitea-issues/gitea-prs
boundary, which defended against nothing -- neither was going to win a release
request. Kept the indirect trigger and the one real near-miss, gitea-branches.
Releases and tags are one flow, not two: 'delete the release and its tag' is a
single invocation that takes both branches, which disqualifies mutual
exclusivity, so no dispatch split. Two Gotchas moved to references/ behind
explicit triggers; one deleted as a paraphrase of the step below it.
Refs #99
Follow-up to the review of #106, which found four parameter claims the
first pass left wrong or missing. All four verified against gitea-mcp
v1.6.0 source before changing anything.
`remove_deadline` is dropped on "create" like the others, but the new
Gotcha enumerated a closed list that omitted it — so the paragraph
contradicted its own opening sentence. The list is now open ("including")
and the parameter carries the same "update" only marker as its neighbours.
`base` is settable on "update": editPullRequestFn reads it and retargets
the PR onto a different base branch. The file documented it as required
for "create" and said nothing else, hiding a real capability. This one is
under-claiming rather than over-claiming, but a file whose subject is
which parameter applies to which method is the place to fix it.
applyDraftPrefix strips two prefixes, `WIP:` and `[WIP]`, matched with
strings.EqualFold, while only "WIP: " is ever added. The un-draft
correction said "the prefix" singular, which understates what a caller
can hand it.
README.md bundled `reviewers` and `milestone` into "creating and
updating". Capability prose rather than a parameter contract, so not
strictly false, but it is the same conflation that produced the original
bug and it is not behind any gate.
Not addressed here: SKILL.md's description still advertises updating
reviewers, its draft guidance still prescribes the manual workaround, and
its milestone-resolution instruction carries no method qualifier — so an
agent working from SKILL.md alone can still reach the failure mode. Those
edits trip skill-size-check and the Vale prefilter, pulling in the
ADR-0020 retrofit; tracked on #99 rather than done silently here.
Refs: #104
Refs: #99
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ETxbGFetkbJQBHsx442Brt
The gitea-prs reference documented `milestone` as "settable on both
"create" and "update"". It is not: `pull_request_write method: "create"`
accepts the parameter, returns no error or warning, and discards it.
Verified against the gitea-mcp v1.6.0 source rather than by observation
alone. `createPullRequestFn` builds its `CreatePullRequestOption` from
owner, repo, title, body, head, base, draft, labels and deadline only —
so the drop is not limited to `milestone` as issue #104 supposed.
`assignee`, `assignees`, `reviewers` and `team_reviewers` are discarded
on create too, and `reviewers`/`team_reviewers` are discarded on
"update" as well; they are only ever read by "add_reviewers" and
"remove_reviewers".
Two properties made the original error easy to make and hard to catch,
so both are now written down next to the correction: `labels` sits
beside `milestone`, reads identically, and does apply on create; and
`issue_write method: "create"` honours `assignees` and `milestone`, so
the asymmetry is specific to pull requests.
While in the file, corrected the adjacent draft gotcha. It prescribed
reconstructing the un-prefixed title by hand to un-draft a PR;
`applyDraftPrefix` shows "update" with `draft: false` and no `title`
fetches the stored title and strips the prefix server-side.
Impact: documentation only, no behaviour change. Callers following the
old text silently created PRs with no milestone, assignee or reviewer.
Confined to references/pull-requests.md, so the ADR-0020 skill gates do
not apply and gitea-prs needs no #99 retrofit first.
Fixes: #104
Refs: #99
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ETxbGFetkbJQBHsx442Brt
Why: enumerating a plugin's skills in its published description has now failed
three times in four days, the third time inside the correction for the second.
bb9158d (Aug 14) fixed core's description, which described bin's skills. That
failure was wrong content, not an incomplete list -- a syntactically perfect
four-item enumeration that belonged to a different plugin -- so enumerating
harder could not have caught it, and bb9158d's own fix replaced the enumeration
with a domain boundary. 65bac15 and de84d1b then cited that precedent while
doing the opposite, and the re-enumeration is itself incomplete: caveman and
zoom-out are unnamed in bin, git-workflow is unnamed in git despite 65bac15's
message claiming it was added, and gitea-workflow is unnamed in gitea. 23 of 27
skills named at the third attempt.
Nothing checks any of this. check-manifests.sh does not contain the string
"description"; apm audit --ci, apm pack --check-clean and
sync-plugin-content.sh --check all compare compiled output against apm.yml, so
their job is to propagate whatever it says byte-for-byte. The wiki claim passed
all fourteen pre-push hooks every day it was published. Enumeration also makes a
marketplace release the consequence of a directory appearing.
Implementation notes:
- ADR-0021 records the decision, the three failures, and why no gate is added:
the check is one-directional, cannot see an invented capability, and a
correspondence map would relocate the same per-skill maintenance one file over.
- bin 1.1.4 -> 1.1.5, git 1.3.4 -> 1.3.5, gitea 1.3.5 -> 1.3.6,
marketplace.version 0.4.4 -> 0.4.5, all PATCH under per_package.
- apm.yml's top-level version: is restored to lockstep at 0.4.5. It has moved
with marketplace.version in all eleven commits that ever touched the file
until this branch left it at 0.4.2, and apm.yml's own comment records it as
live and consumed by apm audit.
- git's boundary names the pre-commit hooks explicitly: pc-author and pc-run are
not git operations, and a boundary drawn narrower than the contents is the
same defect one level up.
- Regenerated with apm pack for the marketplace manifests and
sync-plugin-content.sh --all for the per-plugin ones; both mirrors verified
byte-identical.
Impact: consumer-facing. 16/16 pre-push hooks pass, suite green, generated diff
is 26 insertions and 26 deletions across 8 files with no incidental churn.
Refs: #105
ADR: 0021
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
Why: bin's marketplace description read "A place for things to be binned" — a
routing boundary sitting in the enumeration slot, phrased as a joke. It is what
a consumer sees in the marketplace listing for a plugin shipping eleven
substantive skills: research, write-docs, tdd, prototype, triage, diagnose,
improve-codebase-architecture, grill-me, grill-with-docs, zoom-out and caveman.
This is the same category error b0ef503 fixed for git and gitea, and the same
text bb9158d moved out of core's description in August — "triage, diagnosis,
architecture review" left core precisely because those skills live in bin, so
bin is where it should have landed.
Implementation notes: bin 1.1.3 -> 1.1.4, marketplace 0.4.3 -> 0.4.4, PATCH for
metadata under the per_package strategy. README's bin line mirrors the new
description. architecture.md's routing boundary is deliberately left as
"unsorted skills that have not earned a home yet" — that is still true, and it
answers a different question than the listing does.
Impact: consumer-facing. apm-pack-check-clean, check-plugin-content-sync,
check-marketplace-mirror-sync, validate-marketplace, validate-plugins and
apm-audit-ci all pass.
Why: both plugins' published descriptions named capabilities that do not exist
and omitted ones that do. `gitea` advertised wikis — no wiki skill exists and
`grep -ri wiki plugins/gitea/.apm/` is empty — while omitting gitea-branches and
gitea-files. `git` advertised pull requests, which are gitea's, while omitting
pc-author/pc-run, git-submodules and git-workflow. These are compiled into
plugin.json and both marketplace.json files, so they are published metadata, not
internal notes.
This is the same defect bb9158d fixed on `core` in August, so the fix follows
that precedent exactly: correct the package apm.yml and the root marketplace
entry together — fixing only the package manifest leaves it half-propagated,
since the root entry is what reaches the compiled marketplace.
Implementation notes:
- git 1.3.3 -> 1.3.4, gitea 1.3.4 -> 1.3.5, marketplace 0.4.2 -> 0.4.3, all
PATCH for metadata under the per_package strategy at apm.yml:76.
- Regenerated with `apm pack` for the two marketplace manifests and
`scripts/sync-plugin-content.sh --all` for the four per-plugin plugin.json
files; `apm pack` alone does not touch those. `scripts/sync-marketplace-mirror.sh`
refreshed the Copilot legacy mirror, which no apm profile targets.
- README's gitea line mirrors the new published description. The routing
boundaries in architecture.md deliberately do not, since they answer a
different question.
Impact: consumer-facing. Anyone reading the marketplace now sees what these
plugins ship. apm-pack-check-clean, check-plugin-content-sync,
check-marketplace-mirror-sync, validate-marketplace and apm-audit-ci all pass.
Closes the second open design decision on PR #103. The `/compact` finding was
recorded as a false positive needing an allowlist or a suppression mechanism.
It is neither: the routing universe is the apm marketplace, so a target either
resolves to a skill or an agent or it does not resolve, and `/compact`,
`/clear` and `/init` are Claude Code slash commands with no counterpart in
Copilot CLI or Codex. `.apm/` source compiles for all three, so a
vendor-neutral description routing to one is a portability defect and the hard
FAIL is a true positive.
An allowlist was rejected for a concrete reason, not a stylistic one: it
answers a different question ("does this exist on some host?"), it cannot
answer that portably from a single source file, and it goes stale the next
time a host ships a command — reintroducing the same-commit-two-verdicts
failure ADR-0020 already closed for deployed trees.
Nothing is blocked today: zero of the 43 descriptions name a host built-in,
and an author who needs to mention one writes it un-slashed, which is not
route notation and carries no routing claim.
Recorded in ADR-0020 and in both author-facing contract references, so the
next agent reads the decision rather than "fixing" the gate.
ADR: 0020
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A prose-form routing target blocks a commit only when its own sentence names
another target that resolves. That makes the sentence splitter part of the
ADR-0020 contract rather than an implementation detail, and the naive
"period, space, capital" rule got it wrong in both directions:
- OVER-SPLIT: `e.g. "..."` is not a sentence end, but the quote looks like a
start. The clause was cut in half and the corroborator stranded on the far
side, so a genuinely dangling target silently demoted to SUGGESTION — a
measurement taken and then discarded, the vacuous-green shape this gate
exists to prevent. Seven such splits are live in the current corpus.
- UNDER-SPLIT: a sentence opening with a code span or a lowercase skill name
was not seen as a start, so two sentences merged and a resolving target
vouched for an unresolvable one it never stood beside — a hard FAIL with no
escape hatch, which is the exact failure corroboration was added to prevent.
The splitter now excludes the five abbreviations that occur in routing prose
and admits a backtick or lowercase letter as a sentence opener. Applied
byte-identically to all three copies of the shared resolver.
Verified zero-delta against the corpus: 37 ERROR / 58 SUGGESTION / 2 dangling
before and after, findings byte-identical. The exposure this closes is to the
descriptions #99 is about to rewrite, not to the ones already measured — which
is why the deferral reason recorded on PR #103 ("can move the documented corpus
counts") does not hold and the fix lands here rather than after the retrofit.
Three regression tests, one per direction plus the backtick opener, each proven
non-vacuous by reverting the splitter alone and watching it go red.
Refs: #99
ADR: 0020
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Diffing each retrofitted SKILL.md against its replacement references/ files found
rules that existed on main and now existed nowhere — relocated in intent, deleted in
fact. A trim that loses a rule is not progressive disclosure, it is data loss with a
smaller word count.
Three had no survivor. The least-privilege guidance for `tools` kept its mechanics
and lost the "restrict to what the agent needs" half, so the remaining text read as
encouragement to omit the field. The improve flow lost its regression check, so
nothing compared the closing audit against the pre-edit state and a PASS quietly
becoming a SUGGESTION went unnoticed — restored on both halves of the author pair,
since agent-author had dropped its equivalent too. And agent bodies lost "would the
agent get this wrong without it?", which mattered more than it looks: ADR-0020
deliberately sets no body word gate for agents, three of the four already sit
between 933 and 1,199 words, and the delegation check only fires on procedure a
skill already owns. That heuristic was the only brake left.
Two more were reachable only from the wrong scope. agent-author tells the reader to
load only the file for the resolved scope, but the mcp__ glob syntax for
disallowedTools and the five tools no subagent ever receives had both landed in
project-user-scope.md. disallowedTools is the ONLY permitted fence at plugin/APM
scope, so the scope that needs the syntax most could not reach it, and a plugin-scope
run could write a body telling the agent to ask the user a question.
Two documents were actively wrong rather than merely thin. agent-audit told auditors
that validate.sh resolves boundary targets for skills only; it runs at both scopes,
so the auditor was hand-resolving what the script had already decided and could
contradict it. And skill-audit routed to its script-troubleshooting reference
whenever validate.sh "fails" — but it exits 1 on ordinary content FAILs, the normal
outcome for the whole #99 population, so 1,302 words loaded on nearly every audit.
A context-budget regression inside the skill that enforces the context budget.
Finally, two illustrations taught the shape the gate ERRORs on, unfenced, while an
adjacent rubric called it a hard ERROR.
LESSONS.md records the reference-chain depth rule flipping from "one level deep" to
"two hops, never three". ADR-0020 is silent on it and the reversal rode entirely on
the diff; the looser rule is what mandatory dispatch requires.
Refs: #99
ADR: 0020
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015W3iwF9ncfRZddGBxsMCYi
Every defect fixed in f7cc279 was reachable because nothing asserted against it.
The gate had 43 assertions and none of them covered a consumer repo, a non-string
description, an unclosed fence, or the two spec ceilings. Each case below fails
against the pre-fix code and passes against the current one; every one was proved
non-vacuous by mutating a scratch copy of the script and watching the test go red,
independently twice.
The two that mattered most had no fixture anywhere. A consumer repo WITH .git is
the shape the resolver exists to serve, and only the no-.git case had ever been
tested, which is exactly why the blocker was invisible. And ADR-0020 says the
walk-up runs in two passes specifically so a nested .git cannot beat a plugins/
root further up — no fixture had ever placed a .git inside a plugin.
test-adr0020-differential.sh loses _non_adr_hook_error(). It excluded MAX_LINES and
MAX_WORDS from the cross-script comparison on the untested assumption that awk and
splitlines() agree. They do not, and the divergence stayed invisible for exactly as
long as the exclusion stood. The ceilings are now compared like any other rule.
Two existing assertions were repairs, not additions. The skill-improve probe had
been fixed by this very branch, so its iteration permanently took an
assertion-free SKIP that still counted as a pass; both branches now fail loudly and
each names the other file's pin so the two stay in step. And the yaml-none fixture
emitted `---/---`, which never matched the frontmatter pattern at all — it passed on
the bare word "frontmatter", present in both messages, while never reaching the
branch it was named for. Needles throughout that file now name their branch.
Refs: #99
ADR: 0020
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015W3iwF9ncfRZddGBxsMCYi
Review of the ADR-0020 gate found four ways it could exit 0 without measuring, and
one way it hard-failed a repo it had no business failing. On a gate shipping hot
with no baseline, a silent pass is the worst outcome available and a false block is
the second worst.
Consumer resolution was the blocker. _authoring_root() fell back to the nearest
.git, so it returned truthy in ANY git repo; _collect_authoring_root() then
contributed nothing and the deployed-tree branch was dead code in precisely the
consumer case it exists for. A consumer repo routing to an installed sibling got an
unblockable ERROR, and deleting .git "fixed" it. It now keys on which of the two
walk-up passes matched. A name-count delta was tried first and is wrong: a
single-plugin monorepo re-collects its own package and adds no new name, so the
delta reads zero and drags the deployed trees — including a global ~/.claude — back
into the universe. That reintroduces the install-dependence ADR-0020 forbids, one
layer down.
The three silent passes: an indented `---` inside a block scalar truncated the
frontmatter and reclassified the rest of the description as body; a non-string
description was str()-coerced, so `description: true` measured as the four-character
"True"; and an unterminated fence blanked the rest of the body, disabling the
ERROR-tier references/ check and the gotcha counts.
Two measurement defects came with them. The awk line/word counts discarded awk's
exit status, so an unreadable file passed both spec ceilings in total silence, and
awk NR/NF disagreed with the audit script's splitlines()/split() on Unicode
whitespace — the "fix one gate, get blocked by the other" bug, on the two axes the
differential test deliberately excluded. Both counts now run in the Python block
that already reads the file. A type error also no longer reports itself as a syntax
error.
Also: glob metacharacters in the checkout path silently disabled the resolver;
re.I was applied to some extraction patterns and not others; agent-audit missed
`tools:` written as a YAML block sequence, the shape Copilot files use; and a
nonexistent agent file raised a bare FileNotFoundError instead of a diagnostic.
The shared resolver block stays byte-identical across all three scripts. Corpus
output is unchanged — 26 description FAIL, 9 body FAIL, 2 dangling, 0 missing
references, 58 SUGGESTIONs — so no documented count moves.
Refs: #99
ADR: 0020
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015W3iwF9ncfRZddGBxsMCYi
The four preceding commits change `plugins/kyberforge/.apm/` content that reaches
the compiled artifacts — three validators, a new reference file in each of
`skill-audit` and `skill-author`, and the authoring rules across both author
skills — so per `apm-workflow`'s configure policy the package earns a bump, minor
for the new capability.
Root `apm.yml`'s `executables.allow` key moves with it, in this commit and not a
later one. apm approves a package's `hooks/` and `bin/` by an exact
`<name>#<version>` dictionary lookup with no wildcard and no version-less form, so
a `kyberforge#1.5.0` key left behind a 1.6.0 package errors nowhere: the entry
stops matching, the `SessionStart` freshness hook stops deploying, and the install
goes quietly stale. That is the failure ADR-0019 records as having actually
happened, and `check-executables-allow-sync` exists to catch it.
The catalog bump was missing from the working tree and is added here.
`apm-workflow`'s marketplace policy is explicit that an existing entry's
`version:` moving earns the catalog a **patch** — the set of packages is
unchanged, only its metadata moved — and that the root `version:` stays in step
with `marketplace.version`, since apm audit reads one and the compiled manifest
carries the other. Nothing enforces this: `apm pack --check-clean` catches a bump
made in `apm.yml` but never re-packed, while a bump never made at all fails
nothing.
Manifests regenerated with `apm pack` plus `scripts/sync-marketplace-mirror.sh`
for `.github/plugin/marketplace.json`, which no apm output profile targets.
`.agents/plugins/marketplace.json` is unchanged — the codex profile's shape
carries no version field for either the catalog or its entries.
Six defects, each one a place where two files that an author reads in the same
sitting told them different things — or where the trim dropped a rule and nothing
noticed because no gate covers prose.
**"Use proactively" contradicted itself across the pair.** All three agent
templates said to add it where the runtime should delegate unprompted, while
`agent-audit`'s `KyberforgeCopilot.ProactivePhrase` rule grades it a hard FAIL in
any `*.agent.md` — which is the Copilot half of every project/user pair *and* the
vendor-neutral plugin-scope file, since that compiles to a real Copilot agent
downstream. Following the template produced a file the repo's own gate rejects.
The phrase is now permitted in exactly one place, the Claude Code `.md`, and
`references/contract.md` carries the per-file table plus the consequence authors
ask about next: a pair whose CC half has it and whose Copilot half does not is
correct, because `agent-audit` checks that both halves describe the same job, not
that they match word for word.
**The output-schema rule contradicted itself inside one file.** `contract.md`
said any content only one branch reaches moves to `references/`, and then offered
an "Output format template" body pattern with no qualification. Stated once now,
so it is not re-litigated: an output schema stays in the body only when every flow
produces it and it is roughly 50 words or less. No third option.
**Gotchas tiers disagreed with the script.** `validate.sh` emits the entry count
through `suggest()` and exits 0, while `skill-author` and `skill-audit` both
called more than five entries a FAIL. Whether a given gotcha earns its place is
judgment, so the prose moves to the script's tier rather than the reverse. The
paraphrase rule stays a FAIL and is explicitly marked as the auditor's call — no
script detects it.
**The dispatch exemplar was cited at the wrong number.** `apm-workflow`'s body is
421 words; 554 is its whole-file count. Both `contract.md` and `body-discipline.md`
cited 554 while describing a body budget, so an author calibrating against the
exemplar overshot by ~30% — the exact whole-file/body-only conflation those two
sections exist to warn against, reproduced inside the warning.
**"Error handling" came back as a required body element.** It was one of four and
is the one that gets dropped, and dropping it is not neutral: an agent handed
malformed input with no instruction invents a recovery, and a subagent's invented
recovery is invisible to its caller until the output is wrong. Restored in
`agent-audit`'s rubric as a SUGGESTION, in `agent-author`'s contract and both
scope checklists as a required element, and as an `## Errors` section in all three
templates.
**`skill-author` Step 4 gains the one check the audit misses.** An empty body
reports `PASS SKILL.md body word count 0` — a word gate cannot tell "concise"
from "absent". Step 4 now hand-checks for a non-empty section, and its commit
verification is conditioned on actually being inside a git worktree, which a skill
under `~/.claude/skills/` is not.
Also here: absolute repo paths removed from `skill-author`'s SKILL.md and
contract.md in favour of naming the skill (`zoom-out`'s description is quoted
inline instead of pointed at), the boundary-target universe documented to match
the resolver, a two-hops-from-SKILL.md limit on reference chains, and
`new-agent.sh`'s next-steps output naming the description budget and the
deliberate absence of an agent body gate.
Refs: ADR-0020
ADR-0020 shipped its gates hot with no baseline file, so 26 of 39 descriptions
and 9 of 39 bodies are over their FAIL tier and editing any of them for any
reason requires bringing the skill into contract first. `references/improve.md`
said exactly that and stopped there — it mandated a retrofit and supplied no
procedure for one.
Four dry-run retrofits confirmed what that costs. Asked the same questions —
what to cut first, when a body is two flows rather than one, what else has to
change alongside — they invented six to ten different answers, so the same skill
retrofitted twice produced two different skills and neither run could be reviewed
against anything.
`references/retrofit.md` fixes the answers: an ordered cut list ranked by tokens
removed against behaviour lost (inverting that order is how a retrofit deletes the
instruction the skill existed to carry), the test for whether a body holds two
mutually exclusive flows, the reference-file conventions, the collateral checklist
for `README.md` and `references/sources.md`, and a worked description retrofit.
It also states the trap the dry runs kept hitting: retrofit the skill in place,
inside its package. The boundary-target universe is built by walking up from the
file being checked, so a scratch copy has no authoring root above it, the check
prints `INFO ... DID NOT RUN`, and the run still exits 0 — a line that reads as a
pass and is not one. A retrofit signed off on a copy carries an unverified
boundary target into the corpus.
Loaded from the improve flow only when a budget is actually exceeded, so a routine
improvement pays nothing for it.
Refs: ADR-0020, #99
The ADR-0020 body trim took `skill-audit` from 2,623 body words to a dispatch
shape, and two things went out with it that were not padding.
The manual structural fallback was one. Its replacement was a single sentence
telling the auditor to report an INFO when `validate.sh` cannot run — so with no
`python3` or no PyYAML, `skill-audit` reported the gap honestly and then audited
nothing structural at all. Every ADR-0020 measurement, the whole-file ceilings,
the name-to-directory match, the `references/` pointer check and the script
hygiene checks silently left the audit. A skill's whole Structure dimension
hanging on one optional interpreter is the same vacuous-pass shape the gate
scripts were just fixed for, one layer up.
The `E100 Runtime error ... does not exist` diagnostic was the other. That exit
code means an explicit relative `--config` was passed to `vale-wrap.sh` while
vale itself was installed and working; without the note, Step 1's fallback reads
exit 2 as "vale unavailable" and downgrades the description, body-discipline and
patterns dimensions to full LLM judgment for a config error it could have fixed.
That misreading is already recorded in CONTEXT.md as the reason both audit skills
stopped passing `--config` at all.
Both are restored in `references/validation-scripts.md`, loaded only when a Step 1
script fails — so the body pays nothing for them on a clean run, which is what the
dispatch pattern is for. The file also carries the by-hand boundary-target
procedure and the three ways to misread the result, including that
`INFO ... DID NOT RUN` is not a pass.
`references/file-structure.md` gains the one sanctioned spelling for a cross-skill
reference. The possessive form (``skill-audit's references/validation-scripts.md``)
is the only spelling both rules accept: a full repo path is what that section
already forbids, and a bare `references/<file>.md` is now a hard ERROR from the
ADR-0020 pointer check, which requires the file to exist in the skill's *own*
directory. Without the rule the two constraints look mutually exclusive.
Refs: ADR-0020
