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
Three ways the gates could report green having measured nothing. All three were
invisible to a passing test suite, because pre-commit prints nothing at all for a
hook that exits 0 — a gate that declines to check and a gate that checked and
passed produce the identical signal.
- A UTF-8 BOM, a leading blank line, a trailing space after a `---` marker or
CRLF line endings defeated the `^---\n` frontmatter matcher. Every ADR-0020
check was then skipped and the file passed: measured at the time, a
550-character description with a 1,000-word body exited 0 behind a BOM.
All four shapes are now tolerated, and frontmatter that genuinely cannot be
parsed is a hard ERROR rather than a silent skip.
- An agent file with a valueless `description:` followed by another key let a
line regex capture the *next* key, which looked non-empty, so the
missing-or-empty branch never fired and every gate below it early-returned on
the empty folded value — zero output, exit 0, on a blocking gate. The one
field this contract is entirely about was the one field a gate could fail to
notice was absent. Presence is now decided on the YAML-folded value and
nowhere else, and a missing or empty description is a hard FAIL in all three
validators.
- The hand-rolled frontmatter fallback disagreed with PyYAML across the FAIL
boundary on folded scalars, so which reader happened to be available decided
the verdict. A fallback that mis-parses a scalar shape reports a vacuous pass,
which is worse than not running, so it is deleted: python3 and PyYAML are hard
requirements that fail loudly with an install pointer.
Boundary-target resolution no longer derives its universe from its own location.
A `${BASH_SOURCE}`-relative repo root leaked this repo's 39-skill universe into
every consumer repo running the hook through pre-commit, so a consumer skill
routing to `skill-audit` resolved against a plugin it had never installed. The
interim form resolved through `.claude/` and `.agents/`, which are gitignored
`apm install` output — the same commit reported 2 dangling targets on a machine
that had run the install and 6 on a fresh clone. Resolution now walks up from the
file being checked to an authoring root (nearest ancestor holding
`plugins/*/.apm/{skills,agents}`, else the nearest `.git`, in two passes so a
nested `.git` cannot outrank a real monorepo root); the universe is every skill
and agent under `<root>/plugins/*/` plus the file's own apm package and that
package's declared `dependencies.apm`. Deployed trees are consulted only when no
authoring root exists at all — the consumer case. One commit now gets one verdict,
which a gate shipping hot with no baseline file has to.
Narrowed in the same pass: a routing target inferred from the prose boundary form
and corroborated by nothing else reports at SUGGESTION instead of blocking. A
blocking check with no escape hatch is the wrong trade when the inference from
prose is the weak part of it.
New deterministic checks, all previously untested or absent: every
`references/<file>.md` a body names must exist (ERROR — a broken pointer is not a
style opinion); a description with no boundary clause at all, a Gotchas section
over five entries, and a Gotchas section over 25% of the body are SUGGESTIONs.
Where no universe can be determined the target check prints `INFO ... DID NOT
RUN` rather than passing quietly. Each prose-scanning check needed its own
false-positive fix — a fenced example of a Gotchas section was being read as the
section itself — and those fixes are pinned rather than assumed.
The resolver is one block copied verbatim into all three scripts between
BEGIN/END markers, because a cache-installed plugin's scripts cannot read outside
their own plugin directory. Nothing asserted the copies were still identical; a
one-line edit to a single copy passed every constant-agreement assertion, since
constants are not what drifts.
Tests land here rather than in a later commit. The existing suites assert the old
behaviour and go red against these scripts, so splitting them would leave a commit
whose own `run-tests` pre-push gate fails in isolation.
Refs: ADR-0020
plugins/lint/hooks/hooks.json was no longer produced from .apm/hooks/,
so check-plugin-content-sync failed on it at HEAD:
DRIFT plugins/lint/hooks/hooks.json: stale, no longer produced from .apm/hooks/
Surfaced by running sync-plugin-content.sh --all during unrelated work.
Unrelated to ADR-0020; committed separately so the contract change stays
reviewable on its own.
Per ADR-0017's 2026-08-14 amendment, a hooks.json a sync no longer
generates is deleted as stale.
Skill name+description pairs are preloaded into every session, costing
~6,200 tokens across 39 skills before any skill is invoked. The authoring
rules mandated that growth: skill-author:104 and description-quality.md:21
both required padding, while skill-author:102 (the deflating rule) had no
FAIL condition behind it.
Gates (blocking, no baseline file):
- description 250 chars SUGGESTION / 400 FAIL, measured on the folded
YAML value
- body-only 600 words SUGGESTION / 900 FAIL, independent of the unchanged
whole-file 2770-word / 500-line spec backstop
- every boundary-clause routing target must resolve to a real skill or
agent; catches skill-improve, neuledge-context and gitea-labels
- agents take the description gates but deliberately no body gate; a test
pins that absence
Vale: DescriptionOpener widened to ^This\b, new CompositionNote rule
banning architecture notes from descriptions. 10 hits, 0 false positives.
Kyberforge's own four skills retrofitted: descriptions 3,364 -> 938 chars
(-72%), bodies 8,306 -> 2,487 words (-70%), all via the apm-workflow
dispatch pattern. Fixes the skill-improve dangling route and the
agent-author misroute to manual review.
Also fixes a pre-existing false positive where any line-initial 'read '
was flagged as interactive input, which had already caused two scripts to
be rewritten around it.
Refs: ADR-0020
Deploys kyberforge's SessionStart apm-currency hook into
.claude/settings.json (ADR-0019), bumps bin 1.1.2->1.1.3 and
kyberforge 1.4.1->1.5.0 in apm.lock.yaml with new exec_status
fields, and removes lint's now-empty .apm/hooks/ source dir
(the generated hooks/hooks.json mirror is untouched).
apm prints "1 outdated dependency found" in the singular when exactly one
package is behind (apm_cli/commands/outdated.py). check-apm-current.sh
matched only "outdated dependencies found", so one stale package was
invisible: the hook exited 0 silently and no refresh ran. With six
packages merging independently, one-behind is the ordinary case, so the
freshness mechanism failed most often in the situation it exists for.
Three further defects in the same hook:
- The host timeout was below the script's own budget. hooks.json declared
320s while the script allows `timeout 60` plus `timeout 300` = 360s, so
a slow remote let the host kill the hook mid-update and leave
.claude/skills/ half-deployed with nothing emitted. Now 380. A test
asserts the invariant rather than the literal: it sums every `timeout N`
parsed out of the script and requires hooks.json to exceed it, so
changing either side alone fails.
- The lockfile guard was cwd-relative, so a session opened in a
subdirectory no-opped silently and ran both apm calls against the wrong
directory. Now anchored on CLAUDE_PROJECT_DIR, falling back to the cwd
so the hook stays inert under a host that does not set it.
- Every assertion mocked apm, so the suite was green over code that could
not detect its own most common trigger. That blind spot is what hid the
singular/plural bug, and it is the same shape as the deleted post-push
tests. The suite now stages a genuinely outdated dependency against a
local git remote — offline, via url.<path>.insteadOf, so the
pass-under-unshare property survives — runs the real `apm outdated`, and
replays its output through the real hook. Reverting the grep to
plural-only fails it.
23 -> 35 assertions. Each fix mutation-tested individually. kyberforge
stays at 1.5.0: it is untagged, so this changes what 1.5.0 ships rather
than superseding it, and executables.allow needs no edit.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
plugins/bin/.mcp.json declared the obsidian server as
`npx @bitbonsai/mcpvault@latest`, so an unpinned third-party npm package
was fetched and executed at every session start. The apm-consumed install
promoted that string to committed repo-root content in .mcp.json, giving
every clone the same unpinned execution. Pinned to 0.15.0, the version
`latest` currently resolves to.
bin 1.1.2 -> 1.1.3 and marketplace 0.4.0 -> 0.4.1, following the mapping
bb9158d establishes and 3bfdf58 confirms: the marketplace takes the same
bump severity as the highest-severity package bump. kyberforge is not
bumped here, so executables.allow's `kyberforge#1.5.0` key is untouched.
The pin is not live for this working copy until this lands on the remote
and `apm update` re-resolves — apm.lock.yaml still records 1.1.2 and
`@latest`, because the six dependencies resolve from the remote rather
than from the tree beside them. Correct for a fresh clone immediately.
.gitignore gains /.claude-plugin/plugin.json: a bare `apm pack` emits a
root-package manifest there that has never been tracked on any branch.
Scoped to the file, since the sibling marketplace.json is compiled output
that is committed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
Why
---
The SessionStart freshness hook is a new kyberforge feature and was committed
without a version bump. It also cannot ship unbumped: apm's executable-trust
allow key is version-pinned, so `kyberforge#1.4.1` would have stopped matching
the moment the package version moved, silently blocking the very hook the entry
exists to authorise.
Implementation notes
-----------------
kyberforge 1.4.1 -> 1.5.0 (MINOR, new feature); marketplace and root manifest
0.3.4 -> 0.4.0, following the convention in bb9158d where a package bump carries
the marketplace version with it. The executables.allow key moves to
kyberforge#1.5.0 in the same commit. Compiled manifests regenerated with
`apm pack` plus both sync scripts.
A bare `apm pack` also writes build/ and a root .claude-plugin/plugin.json,
neither of which is repo content — the pre-push gate only ever runs pack with
--dry-run, so they had not appeared before. Both removed; build/ is now
gitignored so a future release does not stage it by accident.
Impact
------
Consumers pinning kyberforge see a MINOR bump. All 15 pre-push hooks pass,
including apm pack --check-clean, so compiled output matches the manifests.
ADR: 0019
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
Why
---
ADR-0018 left deployed skills tracking the remote default branch with nothing
watching for drift. The mechanism that was supposed to cover this,
scripts/git-hooks/post-push, could never have worked: git has no client-side
post-push hook. install.sh copied it into .git/hooks/ so it looked installed,
and it had never once fired. Issue #78 reported it as skipping the gitea
plugin; it was skipping everything.
Refreshing on push was also the wrong shape. Your install goes stale when
someone else merges, so a push of your own is neither necessary nor sufficient
for staleness to have occurred.
Implementation notes
--------------------
kyberforge ships a SessionStart hook (startup matcher only) that runs
`apm outdated`, and when anything is behind runs `apm update --yes` and returns
reloadSkills:true so the running session picks up redeployed content. It exits
silently with no apm.lock.yaml present, which keeps it inert for hosts that
installed this plugin natively rather than through apm.
Two findings drove the wiring, both verified rather than assumed:
- apm resolves ${CLAUDE_PLUGIN_ROOT} against the installed package root, and
`apm pack` keeps only *.json from .apm/hooks/. A .../hooks/<script> reference
therefore points into the generated mirror where the script does not exist —
apm reports "Hook script not found" and deploys a hook aimed at nothing. The
reference must be .apm/-relative, and a test pins it.
- apm's executable-trust gate is OFF unless apm.yml carries an `executables:`
block; until now every hook, bin and MCP primitive a dependency shipped would
have deployed unprompted. Root apm.yml now enables it. The allow key is
version-pinned by apm's design, so a kyberforge version bump silently blocks
the hook until the key is bumped too — called out in the block and the ADR.
Also corrects ADR-0018 and AGENTS.md, which named `apm install` as the refresh
command. It is not: `apm install` deploys from apm.lock.yaml's pinned commit
and does not re-resolve refs. `apm update` does.
Impact
------
Session startup costs ~0.7s when current and ~10.4s when six packages are
behind. Auto-refresh rewrites apm.lock.yaml, so an unexplained modification to
it after opening a session is expected; the emitted notice says so.
.claude/settings.json stops being exactly {"hooks": {}} once the hook lands
there — the merged entry is apm's own output, and the rule that nothing
repo-authored goes in that file is unchanged. .claude/hooks/ and the
.claude/apm-hooks.json sidecar are gitignored install output.
The hook cannot install itself: dependencies resolve from the remote, so it
takes effect only after this merges and `apm update` runs once against the new
default branch.
scripts/git-hooks/ is now empty. install.sh's copy block is kept and
test-git-hooks-install.sh synthesizes its own fixture, so the mechanism stays
tested without requiring a dead hook to exist.
ADR: 0019
Refs: #78
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
Output of scripts/sync-plugin-content.sh --all against this round's .apm/
source edits. No file here is hand-edited.
Carries agent-author's scaffolder and its contract doc into the flat mirror.
No compiled manifest changed: nothing in this round touched apm.yml, so apm
pack and sync-marketplace-mirror.sh both produced byte-identical output.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
batch_run ended with a bare wait, which blocks on every background job the
calling shell has, not the ones it started. Harmless for all three current
callers, but a future caller that backgrounds anything of its own would have
batch_run block on it or consume its status. It now records each $! and reaps
exactly those PIDs.
The `wait "$pid" || true` there is load-bearing: unlike a bare wait, wait <pid>
returns the job's status, so without it a single failing job would abort the
set -e caller at the call site -- before run-tests.sh or sync-plugin-content.sh
could read their .status files and print a summary. Status semantics stay in
those files, exactly as before.
check-vale-style-sync.sh's glob probe discarded vale's exit code and output and
decided purely on a grep, so a failed exec, an OOM-killed vale or a full TMPDIR
was indistinguishable from a real glob defect -- both printed "its glob sections
do not cover a path" with no evidence. A flake seen once in this probe could not
be diagnosed afterwards for that reason. The probe now attaches vale's rc and
output: a genuine glob defect reads "vale exited 0 ... in 0 files", a killed vale
reads "vale exited 137; output: <empty>".
That flake was investigated and not reproduced -- 1680 probes across three
contention setups including an offline namespace, all clean -- so nothing is
changed speculatively. The misattribution is worth recording: it was reported
against tests/test-vale-wrap.sh, which never invokes this script; the assertion
belongs to check-vale-style-sync.sh and reaches a log through a different suite.
Also drops the last stale field roster from agent-author's scaffolder. Its
next-steps hint enumerated "(name, description, model, body only)" -- omitting
disallowedTools, and never accurate anyway, since the template marks only
description and the body FILL IN. Its --help carried the inverted form, already
missing six forbidden fields. Both now state the shape rule and point at
field-inventory.md, and a bats case enforces all-or-nothing: name every
allowlisted field or name none, since a partial roster is the shape that goes
stale silently.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
apm's bundle exporter drops symlinks entirely, so a symlink under .apm/ never
reaches the mirror -- and no gate could see it, because every existing check
diffs the live mirror against a bundle-derived copy and both sides lack the
file. It is an absence with nothing left to mismatch against, the only class of
.apm/ content that vanishes without a trace. check_apm_symlinks reads the .apm/
source tree, where the loss is visible, and fails both modes. Reported rather
than resolved: dereferencing would make a real sync emit content the bundle does
not contain, which is the reimplementation ADR-0017 rejects.
--check --all could also pass having verified fewer plugins than the marketplace
lists: a plugin whose .apm/ had gone was SKIPped rather than counted, and the
earlier floor only caught zero. The count is now checked against the marketplace's
own local-package list. There is no exempt state -- ADR-0015 makes .apm/ the sole
authoring source for every local plugin, so a listed plugin without one is drift.
On the Copilot hooks gap, the decision is to document, not implement. Copilot
declares no hooks path and apm emits none, which looks like the mcpServers case
-- but that exception holds because .mcp.json is one host-agnostic format both
ecosystems read, so a pointer to it is true whatever it contains. Hooks have no
shared format: Claude expects nested matcher groups under PascalCase events,
Copilot requires version: 1, camelCase, and a bash/powershell split. apm merges
.apm/hooks/*.json into exactly one file, at Claude's convention path. A pointer
would assert a Claude-shaped file is Copilot-shaped -- an incomplete manifest
traded for a wrong one -- and it is not inert today either, since {"hooks": {}}
lacks Copilot's mandatory version key. A test pins the decision, so restoring the
pointer fails until someone confronts the schema mismatch.
Tests: 77 -> 92 assertions.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
Output of scripts/sync-plugin-content.sh --all against this round's .apm/
source edits. No file here is hand-edited.
Carries the agent-author and agent-audit documentation changes into the flat
mirrors. No compiled manifest changed: nothing in this round touched apm.yml,
so apm pack and sync-marketplace-mirror.sh both produced byte-identical output.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
The previous round taught agent-audit's validator to permit disallowedTools but
left the skill that writes agents still forbidding it, in six places. Running
agent-author on any of the three fenced orchestrators would have stripped the
fence, and nothing would have caught it: the validator's allowlist is a permit
list, so an absent field passes. The template was the worst of them, since its
comment is copied verbatim into every new plugin-scope agent.
Where a list had to be restated it is now a pointer to field-inventory.md's
apm-agent-allowlist instead -- the same data validate.sh reads -- because a
roster copied into a template goes stale one step further out than the roster
itself. Where the text has to teach something it teaches the shape rule rather
than the exception: tools is an allowlist whose vocabulary differs per harness,
so verbatim copy makes one value wrong on one target; disallowedTools is a
denylist, where an unrecognised name denies nothing, so the worst case is a
missing fence rather than a wrongly granted capability.
ADR-0016's amendment claimed an unrecognised key is inert on Copilot while the
same ADR's Context says that behaviour is unconfirmed by research -- asserting
as settled the exact thing it flags as unknown, and justifying it with apm's
compile-time behaviour, which says nothing about Copilot's runtime. It is
rewritten into labelled tiers: confirmed for Claude Code with citations,
inferred by analogy for Copilot with the analogy's limits stated, unverified
where it is unverified, and the residual risk accepted explicitly with its
blast radius. It also no longer claims to restore a write sandbox: the denylist
does not deny Bash, which these agents inherit and legitimately need.
docs/hooks.md called the old root hooks.json a stale sync artifact -- it was
added in the plugin's creating commit and pointed at by main's Copilot manifest
-- and claimed both ecosystems now resolve hooks/hooks.json. Copilot does not:
its hooks field has no default and no compiled manifest declares one, so it
resolves nothing. Recorded as the gap it is, with re-injection noted as a
follow-up rather than asserted away. Its event list is marked partial.
Also: new-agent.bats asserted a hardcoded four-field allowlist and would have
rejected a scaffolded agent carrying the field the ADR now blesses; it reads
field-inventory.md too. And ADR-0016's premise that Claude's tools: is
space-separated was wrong -- it takes a comma-separated string or a YAML list.
The incompatibility with Copilot is the vocabulary, not the punctuation.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
Output of apm pack, sync-plugin-content.sh --all and
sync-marketplace-mirror.sh against this round's source changes. No file here
is hand-edited.
Carries the version bumps and marketplace owner.email into the compiled
manifests, the disallowedTools frontmatter and doc corrections into the flat
mirrors, and changes plugins/bin/.github/plugin/plugin.json's mcpServers from
the inlined server object to the ".mcp.json" pointer. That last file also
returns to 0644: the previous re-injection wrote it through mktemp and carried
0600 across, which no gate could see because the mode check did not cover
.github/plugin/ and git tracks only the exec bit.
.agents/plugins/marketplace.json is unchanged and that is correct -- apm's
codex profile carries neither version nor owner keys, so nothing in this round
reaches it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
AGENTS.md told an offline agent to push with SKIP=apm-marketplace-check and
asserted that hook was "the only one whose failure mode is 'no network'".
Running all 12 pre-push hooks under a network namespace shows two fail, for
one shared cause: apm-pack-check-clean resolves the same remote entry. An
exact pin does not remove the ls-remote, so both hooks are named now.
AGENTS.md also said everything in a plugin root except .apm/ is generated.
Plugin roots carry hand-authored README.md, docs/, bin/, sources.md and
.mcp.json, so an agent would hunt for an .apm/ source that does not exist or
refuse the edit. The rule is positional: immunity belongs to the plugin root,
and anything inside a mirrored directory is still rm -rf'd.
ADR-0017 said apm strips a hooks field. The real loop is (agents, skills,
commands, instructions) -- hooks absent, instructions never mentioned -- and
it can never fire, because synthesize_plugin_json_from_apm_yml only emits the
eight identity fields. The decision stands; the mechanism was overstated. Its
mcpServers amendment is rewritten for the pointer payload and now records the
real reason: inlining bypassed apm's credential sanitizer.
ADR-0015's owner.email and version-pin passages are corrected against the apm
source, and ADR-0016 gains the disallowedTools amendment. agent-audit's
allowlist is data, so it gains disallowedTools too -- the ADR and the
validator that enforces it had come apart.
architecture.md described a root CLAUDE.md that imports two files (it imports
one, plus an RTK block) and pointed at an ADR index that does not exist.
Seven skill READMEs listed tests/ files the mirror strips, promising installed
users files their install lacks; those rows are marked source-only, with the
depth-4 template tests explicitly called out as surviving. And
plugins/kyberforge/hooks/README.md, deleted during the conversion and
preserved nowhere, is restored to a path the mirror does not own -- verified
by running a sync against a scratch copy.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
mattpocock-skills was pinned as the range ^1.2.0 with no lockfile, so apm
re-resolved it against upstream on every pack. An upstream v1.2.4 would
invalidate the committed ref/sha and fail apm-pack-check-clean with exit 4,
blocking every push in the repo at an unrelated moment, triggered by a third
party. ADR-0015 claimed the opposite -- that nothing advances it. Pinned to
1.2.3, which resolves to the already-committed sha, so the only compiled
change is the version key the remote entry alone was missing.
marketplace.owner.email was dropped on a false premise: ADR-0015 said apm has
no key for it, but yml_schema.py defines _AUTHOR_OBJECT_KEYS as {name, email,
url} and the key compiles through. Restored. (displayName is genuinely
unsupported and stays dropped.)
ADR-0016 dropped per-agent tools: because the allowlist shape is unportable --
Claude takes a comma list, Copilot a {Tool: true} map. That holds. But a
denylist has no such conflict: disallowedTools is honoured by Claude Code and
is absent from its plugin-subagent ignore list, and Copilot copies agent
frontmatter verbatim so an unknown key is inert. gitea-orchestrate,
apm-orchestrate and lint-runner were all write-denied on main and lost that
fence silently; only lint-runner's loss was disclosed, and only lint-runner
had prose to fall back on. All three regain the fence, and the two with no
no-edit language gain three statements each. git-orchestrate is untouched --
it legitimately had edit.
Four plugins shipped changed compiled output under unchanged versions,
against the policy this PR itself wrote: bin 1.1.1->1.1.2, git 1.3.2->1.3.3,
gitea 1.3.3->1.3.4, lint 1.1.5->1.1.6, each in both the plugin manifest and
the root packages[] entry. Root catalog 0.3.3->0.3.4: patch, because the set
of entries is unchanged and what moved is the owner block and four versions.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
Documentation asserted things the code no longer did, which is how several of this
round's defects survived three review passes.
- `docs/spec/architecture.md` still described the pre-APM model — "each plugin has a
`plugin.json` manifest" — when no such file exists. AGENTS.md routes agents here
for the current structure, so it was live drift, not archive. Also cited ADR-0012
where ADR-0003 is meant.
- AGENTS.md never said `.apm/` is the sole hand-edited source, while the generated
mirror is byte-identical with no marker — an agent reading only AGENTS.md would
edit the mirror and find out at pre-push. It also omitted that `apm` and `jq` are
now required to push, unlike the `vale` bullet that exists for exactly that reason,
and understated the pre-push gate. `apm marketplace check` hard-fails offline and
`--offline` does not help, so the `SKIP=` escape hatch is documented rather than
new machinery built.
- ADR-0017 carried hardcoded line numbers that drifted twice within one PR, and said
`mcpServers` reinjection was real-syncs-only where the script's own header says
both modes. Line numbers dropped rather than corrected.
- ADR-0015 asserted issue #90 was closed. It is open. Reworded to defer to the
issue's own state rather than depend on someone remembering to close it.
- ADR-0014 said both audit skills pass `--config`; both SKILL.md files say pass none,
and passing one fails with E100. The ADR was wrong.
- ADR-0007 cross-referenced an archived ADR-0011 whose number was later reused.
Disambiguated with a note — renumbering a published ADR rewrites an immutable
record and breaks every existing citation.
- CONTEXT.md claimed `lint-runner` is report-only via a missing `Edit` tool.
Plugin-scope APM agents cannot express `tools:` (ADR-0016), so it is report-only by
instruction now; ADR-0016 accepted that regression but CONTEXT.md was not updated.
- Recorded two undocumented consequences of the conversion: `displayName` dropped
from all six compiled manifests and `owner.email` from the marketplace, and
`mattpocock-skills` silently version-pinned and manually maintained.
- Wrote the version-bump policy issue #90 specified but never delivered. Its previous
carrier, `marketplace-author`, was deleted in this PR, leaving the per-package rule
documented nowhere.
- README fixes: kyberforge listed skills belonging to the `git` plugin and a deleted
hooks path, `bin` advertised an agents directory it never had, and the docs index
listed files that do not exist.
Refs: #90
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
`core`'s description and keywords described `bin`'s skills — triage, diagnosis,
architecture review — while `core` ships the three agentsmd/provider-adapter skills.
Pre-existing text, but this PR compiles it into `plugin.json` and both
`marketplace.json` files, so it became published metadata. The root `apm.yml` entry
carried the same stale text and is the one that actually reaches the marketplace
manifests, so fixing only the package manifest left it half-propagated.
Version bumps follow the per_package policy this PR documents, each landing in both
the package `apm.yml` and the root entry: kyberforge 1.4.0 -> 1.4.1 for the
reference-doc changes, core 1.1.0 -> 1.1.1 for the metadata, catalog 0.3.2 -> 0.3.3
as a marketplace-block-only edit.
The compiled diff is larger than those four changes because the manifests committed
at HEAD were not apm output: `json.dumps(indent=2, sort_keys=True)` reproduces all
three byte-for-byte, i.e. `pretty-format-json --autofix` had rewritten them before
the exclusion existed. Regenerating realigns them to genuine `apm pack` output;
the remainder of the diff is key ordering and UTF-8 escaping. `core`'s keyword
change is a fifth semantic change, invisible at marketplace level because
`marketplace.json` carries no keywords field.
Refs: #90
ADR: 0015
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
The mirror's `tests/` exclusion was depth-agnostic, so it deleted
`skill-author/assets/templates/tests/` — a template the skill scaffolds FROM —
alongside the depth-2 dev fixtures it was meant to drop. Since ADR-0017 makes the
mirror the installed content, the shipped scaffolder was broken: the mirror copy of
`new-skill.sh` exited 2 on `sed: can't read .../tests/README.md`, leaving a
half-written skill, while the byte-identical `.apm/` copy exited 0. `--check` was
green about it.
Check mode was restructured rather than patched because `diff -x` matches a basename
at any depth and cannot express the depth-2 scoping the fix needs — the two modes
could not be made to agree by construction. Check mode now runs the real `sync_dir`
into a throwaway root and diffs with no exclusions, leaving the exclusion rule and
the hooks destination each in exactly one place.
Also fixed here, all previously invisible to `--check`:
- Merged hooks were written to `<plugin>/hooks.json`, which Claude Code does not
convention-scan, while ADR-0017 itself quoted `hooks/hooks.json` as the contract.
Moved, with the legacy path cleaned up as stale. No `hooks` pointer is added to
`plugin.json`, so this does not reopen the option ADR-0017 rejected.
- Only the first drift per plugin was reported: `diff | sed` returns 1 under
`pipefail`, and `set -e` killed the subshell before the remaining checks and
before `FAIL=1`.
- File-mode and symlink drift were invisible, so `--check` and a real sync
disagreed; a find-based type/mode manifest now covers both.
The tests pinned almost none of this — the stale-skill wipe, the check-mode stale
branch, three `MIRROR_DIRS` entries and the hooks newline normalization could each
be deleted with the suite still green. All are now mutation-tested.
Refs: #90
ADR: 0017
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
--check's throwaway pack copy seeded .claude-plugin/plugin.json and
.github/plugin/plugin.json from the real plugin dir, then packed without
--force -- apm pack silently skips regenerating a plugin.json that already
exists, so the diff always compared the copy against itself and never caught
drift in the compiled name/version/description/mcpServers. --force is now
always passed; in check mode it forces regeneration inside the throwaway copy
only, which sync_plugin_manifest() then diffs against the real committed
manifest.
sync_hooks_json() returned early whenever .apm/hooks/ was missing, without
checking whether a stale hooks.json was still sitting at the plugin root from
a prior sync -- unlike sync_dir(), which already detects that kind of orphaned
mirrored output. It now mirrors sync_dir()'s shape: flagged as drift in
--check, removed on a real sync.
Running the corrected --check --all against this repo's own plugins surfaced
3 real orphans: plugins/{git,gitea,core}/hooks.json, empty stubs added in
4edaaac only to satisfy an old plugin.json pointer-field check that no longer
exists (their compiled plugin.json has never had a hooks field, and none of
the three ever had .apm/hooks/). Removed as part of this fix since they're
exactly the drift the corrected check now catches -- leaving them would break
the sync-plugin-content pre-push gate on this branch.
Also extracts two shared helpers into scripts/lib/, sourced by this script and
others so a future bug fix doesn't need hand-applying three times:
- marketplace-plugins.sh: walks marketplace.json for local plugin dirs (this
script's --all branch and check-manifests.sh had near-identical copies)
- batch-run.sh: the bounded-batch concurrent job runner (this script,
tests/run-tests.sh, and tests/run-bats.sh each hand-rolled the same
core-count-capped wait loop independently)
Extended tests/test-sync-plugin-content.sh with coverage for both drift cases
(plugin.json version-bump drift, orphaned-hooks.json drift), including that a
re-sync clears each.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
validate-secrets.sh checked the placeholder allowlist regex against the
whole line before running any secret-pattern regex. An unrelated
placeholder-looking token anywhere on the line (e.g. "example" or
"your-token-here" in a trailing comment) suppressed detection of a real
credential earlier on the same line. Scope the allowlist check to the
matched secret-candidate substring only, which the per-match re-check
already did downstream but the whole-line pre-check short-circuited
before it ever ran.
Extend validate-secrets.bats with a case proving a real AWS-style key is
still caught when a placeholder token sits elsewhere on the line.
Regenerate the flat-mirror copy at
plugins/core/skills/agentsmd-audit/scripts/validate-secrets.sh via
scripts/sync-plugin-content.sh --all per ADR-0016.
