Three findings from the simplification audit were independently
re-verified before execution, corrected, then implemented by
subagents:
- Finding 2 (check-executables-allow-sync): the audit's "drop it"
option was found unsafe (ADR-0019 calls this failure mode silent,
not "visible and recoverable" as claimed); shrunk instead of
deleted, 231 -> 222 lines.
- Finding 31 (CONTEXT.md): "most terms unused by skills" was found
overstated (13 of 28 are model-facing must-keeps); cut only the
9 confirmed true orphans, 28 -> 19 terms. Also de-referenced one
dangling pointer to a deleted term in the Flagged-ambiguities
section.
- Finding 38 (pc-author/pc-run): line count was found overstated
(598 actual vs. 689 claimed); trimmed the two generic reference
files by 60 lines while preserving house-specific content.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
Corrected scope for audit finding 31: the audit's claim that most of
CONTEXT.md's 28 terms are unused was overstated (13 are must-keep,
referenced in model-facing skill references/*.md files). This cuts only
the 9 confirmed true orphans, independently re-verified by grep across
plugins/*/.apm/, docs/, scripts/, and tests/ with zero hits outside
CONTEXT.md (two had a single incidental ADR mention that doesn't
constitute a dependency): Content mirror, apm-consumed install, Vale
audit prefilter, Vacuous green, Management Application, Sycophancy,
HOTL, Preload tax, Skill context contract.
Term count: 28 -> 19. Also removed two Relationships bullets that
existed solely to relate now-deleted terms (Preload tax/Skill context
contract, and HITL/HOTL/Sycophancy), leaving HITL's own entry to stand
alone. The Preload tax entry's self-contradiction (quoting two dated
character counts immediately after saying not to quote either) is
moot since the whole entry is removed. Example dialogue and flagged
ambiguities sections left untouched per scope, including one now-stale
bold reference to "Preload tax" in flagged ambiguities.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
Trim the two comment blocks that re-derived ADR-0019's argument in full
(apm's exact-dict-lookup key matching, and why the PyYAML fallback is not
a hard requirement) down to a short summary plus a pointer at ADR-0019,
which already carries that reasoning verbatim. 231 -> 222 lines.
The hook is kept, not deleted, per the audit's own corrected scope: the
"or drop it" option in SIMPLIFICATION-AUDIT.md finding #2 is off the
table because ADR-0019's Consequences section and the script's own
header both call this failure mode silent, and the ADR says a
silent-staleness failure here is strictly worse than the duplication
this repo's other gates catch.
The dual-reader design (PyYAML preferred, hand-rolled shape-scan
fallback) is also kept as-is: it exists specifically so a missing
python3/PyYAML can't silently skip the check or block every push, which
is exactly the loud-failure guarantee this finding must not weaken. No
genuine redundancy was found in the parsing logic, the per-branch
Why/Fix error messages (each tied to a specific test), or the test
matrix (which verifies the two readers agree across every failure mode)
without cutting something load-bearing -- so those are untouched, and
tests/test-check-executables-allow-sync.sh needed no changes since
script behavior and output are byte-identical.
All 23 tests in tests/test-check-executables-allow-sync.sh pass, and
`pre-commit run check-executables-allow-sync --all-files --hook-stage
pre-push` passes against the real repo state.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
Collapse the per-language hook tables in pc-author's hooks-by-language.md
into one shared-repo table plus an "other repos" table, dropping the
repeated repo/rev/rationale text that just restated what each hook does.
128 -> 92 lines. Kept both "Unverified — not in research corpus" flags
and the rev-freshness caveat.
Remove the generic SSH/proxy CI failure sections, the shellcheck SC-code
listing, and compress the generic validate-config schema-error bullets
in pc-run's failure-patterns.md, all of which just restated
pre-commit.com's own docs. 133 -> 109 lines. Kept the rtk-prefixed
re-stage/recommit fix (ADR-0023), the "do NOT reach for
`pre-commit install -f`" warning, and both gitleaks/shellcheck
not-sourced-from-corpus notes.
Combined cut: 60 lines. Flat mirrors regenerated via
scripts/sync-plugin-content.sh and verified byte-identical
(--check exits 0); no plugin.json drift.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
The Context section still described .agents/plugins/marketplace.json
(apm's codex profile) as an existing, unaffected generated file. It
was removed today in 568ca74; point to the removal instead of leaving
the text describing a file that no longer exists.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
Neither has a real consumer: Codex is not a supported target, and
mattpocock-skills was the sole remote marketplace.packages[] entry
forcing apm-marketplace-check and apm-pack-check-clean to git
ls-remote on every push. Removing both drops .agents/plugins/marketplace.json
(the codex output artifact) and makes every pre-push hook resolve
fully offline. Updates README, AGENTS.md, gates.md, architecture.md,
and ADR-0015/ADR-0021 to match.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
Cut the "Verified fixed" reproduction paragraph carrying explicitly
stale pre-retrofit figures, and condensed the "Current retrofit
status" section's issue-#99 process narrative to the current-state
facts and the commands to check them.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
f11b645 and bde9f7f swept check-manifests and skill-frontmatter
references left over from e647f14 and c8a7c9e, but missed two worked
examples in this vendored pre-commit research doc: a "Validate a
generated file" hook naming the deleted scripts/check-manifests.sh,
and a "SKILL.md frontmatter validation (inline bash, as used in this
repo)" example for the skill-frontmatter hook, folded into
skill-size-check.sh in c8a7c9e.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
c8a7c9e folded the skill-frontmatter hook into skill-size-check but
left validate.sh's FAIL messages, skill-author's create.md, and the
skill template's frontmatter comment naming the deleted hook as the
enforcer -- misleading for anyone tracing a FAIL back to the gate that
raises it.
f11b645 swept check-manifests references but missed a hand-authored
"Local hooks in this repo" table in the git plugin's vendored
pre-commit research doc, which still listed both check-manifests and
skill-frontmatter as active hooks.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
e647f14 deleted scripts/check-manifests.sh but missed three live files
that still named it: the apm-marketplace-check hook description in
.pre-commit-config.yaml, and comments in sync-plugin-content.sh and
lib/marketplace-plugins.sh explaining design decisions by pointing at
a script that no longer exists.
Also deletes list_marketplace_remote_plugin_names from
marketplace-plugins.sh — its only caller was check-manifests.sh, so
it's been dead code since that commit.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
test-governance-layer.sh and test-instructions-and-docs.sh (583 lines
combined) grep markdown files for expected phrases, including a
one-shot "issue 0015 refactor incomplete" assertion made permanent and
an assertion that docs/notes/ exists. Neither is referenced by any
other script or doc.
check-apm-agents-valid.sh is left untouched — it is tied to the
separate, out-of-scope skill-merge finding 14.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
skill-frontmatter was a 62-line bash script inlined in
.pre-commit-config.yaml, re-parsing SKILL.md frontmatter with grep and
awk to check for name/description/metadata.version fields.
skill-size-check.sh already parses the same frontmatter block with
PyYAML for its ADR-0020 checks, so the two checks belonged in one
script.
Adds a ~20-line required-frontmatter check (name, description,
metadata.version as three-part semver) to scripts/skill-size-check.sh.
Removes the inline skill-frontmatter hook from .pre-commit-config.yaml
and deletes tests/test-skill-frontmatter.sh (366 lines). Removes the
79-line "the other hook on that scope" discussion from
docs/spec/gates.md and its now-dangling cross-reference, replacing
both with a one-line note of the fold, and updates the pre-push hook
counts there.
Updates fixture builders in test-skill-size-check.sh,
test-adr0020-body-checks.sh, test-adr0020-targets.sh,
test-adr0020-differential.sh, and test-vale-hooks-consumer.sh to carry
valid metadata.version so the new check doesn't spuriously fail
existing fixtures that predate it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
Six pre-push hooks were validating overlapping sets of the same
manifests. check-manifests (marketplace.json/plugin.json path checks)
is redundant with validate-plugins (claude plugin validate) and
apm-pack-check-clean, which already cover the same ground.
Deletes the check-manifests hook entry, scripts/check-manifests.sh
(282 lines), and tests/test-check-manifests.sh (771 lines).
scripts/lib/marketplace-plugins.sh is kept — it is still sourced by
sync-plugin-content.sh. Updates the now-stale check-manifests.sh
mentions and hook counts in README.md and docs/spec/gates.md.
The apm-audit-ci and apm-marketplace-check hooks named in the same
finding are left untouched — the audit flags them as needing a
separate decision.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
Finding 13: five blocks of near-identical wording were repeated across
skills within a plugin — the gitea "resolve owner and repo" step (5
skills), the 404-masks-403 note (6 files), the manual pagination
explanation (8 files), the git plugin's main/master force-push refusal
(7 files, some with multiple internal restatements), and the bin
skills' domain-glossary/ADR paragraph (5 skills). Tightened each
instance in place — same meaning, fewer words — rather than extracting
to a shared file, which ADR-0014's one-file-per-skill install
constraint rules out. Left the three git skills' structured-result
JSON shapes alone (coupled to the separate, out-of-scope git-orchestrate
merge candidate, finding 19).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
Finding 21: `config.example.json` (and the never-tracked
`.claude/plugins/git/config.json` it documented) was read by
git-orchestrate and git-branches but written by nothing, and the
default-inference fallback (GitHub Flow, with Gitflow inferred from a
`develop`/`release/*` branch) already covered the no-config case.
Removed the config-read step from both, updated git-workflow's
description of the orchestrator to match, dropped the now-dangling
`applied_config` field from git-orchestrate's output shape, and
deleted the config file and its stale example reference in
docs/spec/architecture.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
Checkbox and strikethrough findings 10, 12, and 30, each pointing at
the commit that implemented it (edcc57c, 629320b). Record the decision
on findings 9 and 26 (delete docs/research and docs/notes): declined,
those docs are kept on purpose as context for work sourced from them.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
Finding 30 of the simplification audit. 41 entries had grown to 255
lines; 10 described a write-skill / write-eval bootstrap workflow
whose skills no longer exist in this repo, and the longest entries ran
200-550 words of incident narrative for a one-line lesson.
Deleted the 10 stale entries. Kept 3 same-dated ones (RLHF defaults,
secrets-rule gap, HITL gap) whose content is unrelated to the defunct
workflow and still applies. Removed one open-work entry ("neither part
landed", about CONTEXT.md not being @import-ed at session start)
rather than filing it as a tracker issue -- not turned into an issue,
just dropped; the audit's own commit history and this repo's session
transcript carry the detail if it's wanted later. Compressed the
remaining 30 entries to roughly 60-90 words each.
255 -> 131 lines, 41 -> 30 entries.
Refs: SIMPLIFICATION-AUDIT.md finding 30
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
Two related simplification-audit findings, bundled because they edit
some of the same skill-audit files and splitting would fragment
single-file diffs.
Finding 10: delete 48 per-skill/reference README.md files (they
restated SKILL.md in narrative form and no agent ever loads them) plus
2 scaffold templates. Drop the README criterion from skill-audit's
file-structure.md and finding-criteria.md, and the README-generation
step from skill-author's new-skill.sh; update new-skill.bats to match.
Plugin-root READMEs are kept intentionally, out of scope.
Finding 12: strip historical ADR-0020/ADR-0023 citations and
changelog-style narration from model-facing skill content across
kyberforge and git plugin skills. Delete skill-author's one-time
retrofit.md migration guide and its references. Some ADR-0023 tags
were not narration but check-rtk-prefix's required opt-out marker for
intentionally-bare git commands -- those were restored, not stripped.
Mirror re-synced and full pre-commit/pre-push suite verified green.
Refs: SIMPLIFICATION-AUDIT.md findings 10, 12
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
Removes the ADR-0020 gate summary, the strict test-suite rule, the
pre-push rehearsal rule, and the commit-authoring rule. Each is already
documented at its owning source: docs/spec/gates.md carries the gate
behaviour and both command invocations, README.md carries the pre-push
rehearsal, and the git plugin's own skills carry commit authoring.
AGENTS.md is meant to hold only what applies to every session, so
content with a canonical home elsewhere does not belong here.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88
PR #133 renamed the skill's root-level LANGUAGE.md to references/language.md
but missed a prose mention (not a markdown link) in the overview paragraph.
Fix both the .apm/ source and its generated flat mirror.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88
grill-with-docs, improve-codebase-architecture, tdd, and triage kept
non-spec markdown files at their skill root, in violation of
skill-audit's file-structure.md rule (only SKILL.md/README.md belong
at the root; everything else lives in scripts/, references/, assets/
or tests/). A root-level file is invisible to the ADR-0020
dangling-reference gate, which only resolves unqualified
`references/...` pointers.
- Moved and renamed to lowercase-kebab-case under references/:
grill-with-docs (ADR-FORMAT.md, CONTEXT-FORMAT.md),
improve-codebase-architecture (DEEPENING.md, INTERFACE-DESIGN.md,
LANGUAGE.md), tdd (five files, casing was already fine), triage
(AGENT-BRIEF.md, OUT-OF-SCOPE.md).
- Updated every in-skill link to the new references/ paths, including
link text that still showed the old uppercase filenames.
- Fixed improve-codebase-architecture/SKILL.md's cross-skill citation
of grill-with-docs's two files to the sanctioned possessive form
with the references/ segment included.
- Updated all four skills' README.md file tables to match.
- Regenerated the flat content mirror via
scripts/sync-plugin-content.sh --all.
Fixes#122.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88
The kyberforge SessionStart hook re-resolves dependencies against the
holocron remote on every session start, which routinely leaves
apm.lock.yaml behind the actually-deployed .claude/ content (documented
in AGENTS.md). That mismatch fails apm-audit-ci and apm-pack-check-clean
at the pre-push gate regardless of what's actually being pushed.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88
The "pre-#113 corpus on main trips the gate" case reconstructed the
historical (pre-sweep) corpus from the live `main` ref. `main` is the
moving integration branch, and the #113 fix (ed8c99e) landed back onto
it — so the moment that fix merged, `main` stopped containing the bare
`git remote get-url origin` drift the case exists to catch, and the
assertion "the gate should fail on this corpus" silently flipped to
false. This blocked `git push` on every branch via the run-tests
pre-push hook, unrelated to whatever was actually being pushed.
Pin to 598a7c3, the last commit before ed8c99e where
gitea-issues/SKILL.md still had the unprefixed call. A specific commit
SHA is immutable, unlike `main`.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88
Regenerates `plugins/*/skills`, `plugins/*/agents`, both per-plugin `plugin.json` manifests and the
two marketplace mirrors from `.apm/` per ADR-0017, via `scripts/sync-plugin-content.sh --all`.
The manifests matter beyond tidiness here: `plugin.json` carries the plugin version and wins over
the marketplace entry at install time (calculatePluginVersion precedence). Until this ran, the patch
bumps in the preceding commit were inert for anyone installing these plugins.
ADR: 0017
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
Why: ADR-0022 made `metadata.version` mandatory in SKILL.md frontmatter, but three documents still
instructed the opposite — that `version:`, `source:`, `references:` and `when:` belong in a separate
META.md. That recommendation was never implemented: META.md exists exactly once in this repo, inside
a vendored third-party research example, and all 39 skills now contradict it. A stale instruction
that outranks nothing is worse than no instruction, because an author following it undoes the ADR.
Implementation notes:
- Two LESSONS.md entries deleted outright — their entire payload was the rejected fix. Two kept and
rewritten: the copy-fill entry loses only its META-TEMPLATE clause, and the `model:` entry keeps
the provider-extension fact and the invocation-time boundary rule, which stand on their own.
- One factual error corrected in passing: the `extracted` slug entry claimed provenance is recorded
in META.md. It lives in `references/sources.md` keyed by `source_keys:`, verified against
validate-provenance.sh.
- Both docs/notes files gain `metadata.version` in their required-field lists. Deleting the stale
paragraph while leaving those lists silent would have re-created the gap.
- `bin/write-docs` carried `metadata.version: "1.0"` — the only non-semver value in the corpus, and
the result of relocating its old top-level `version:` without normalising it. Now `1.0.0`.
ADR-0022 records the relocation it previously omitted, which issue #127 had asked it to decide.
Impact: patch bumps for the four plugins whose `.apm/` content changed — bin, git, gitea,
kyberforge. core and lint are untouched and stay put. Root apm.yml's `executables.allow` key and
marketplace package versions move in lockstep; the marketplace release version is unchanged.
Refs: #127
ADR: 0022
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
Three related half-applied changes from #130, each leaving the corpus in a state its own
documentation contradicts.
Why:
- `assets/templates/SKILL.md` shipped `metadata:` fully commented out, and `new-skill.sh` only
substitutes SKILL_NAME. Every scaffolded skill therefore lacked the `metadata.version` ADR-0022
made mandatory and was blocked at first commit by the very hook this PR added. The commented
example also read `"1.0"` — neither the `0.1.0` new-skill seed nor valid semver.
- `agent-audit/references/scope-project-user.md` still joined `disable-model-invocation` and
`user-invocable` with a slash — #125's defect verbatim — while pointing the reader at the file
this PR had just corrected to say the opposite.
- ADR-0022 required the "when present" bump conditional dropped and `metadata.version` moved into
create.md's required list. It was dropped from SKILL.md but left in README.md, and the field was
edited in place under a heading that still authorises removing it entirely.
Implementation notes:
- The template emits `metadata: version: "0.1.0"` live, captioned as required, with the optional
keys left commented. `new-skill.bats` gains a case asserting a live key and three-part semver, so
this cannot regress.
- `description-quality.md` now asserts only what the vendored Copilot research supports: two fields
with opposite defaults, and the retired `infer` replaced by the pair rather than by either alone.
The unsupported negative it previously stated as fact is gone.
- The `1.0.0` retrofit seed is stated in improve.md and retrofit.md, which the retrofit flow
actually reads — create.md, where it lived, is unreachable from that path. The compression item
moved out of the file-churn checklist, whose preamble excluded the wording-only change it covers.
- Executable git commands in these three skills now carry the ADR-0023 rtk prefix.
Refs: #125, #127
ADR: 0022, 0023
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
Check 9 shipped in #130 to close#118, but three defects meant it could not do the job it was
added for.
Why:
- It is INFO-only, so it always exits 0 — and SKILL.md graded exit 0 "a genuine pass" and said the
script "prints nothing on success". Every check-9 INFO was discarded before it reached a report,
behind three further doors that only opened on a non-zero exit.
- `parse_field_raw()` matched `(.+)`, which does not span newlines, so only the first physical line
of a wrapped value was compared. Rewriting only the continuation line of a wrapped Description
from a hedge to a confident claim produced no finding at all — verbatim the regression #118 was
filed about. The bullet branch had the same shape: a wrapped bullet broke the loop and dropped
every later entry.
- A `git show` failure at the base ref was treated as "creation, nothing to flag" and skipped the
whole skill with no output, collapsing "absent at that ref" with "not tracked under that name".
A gitignored `.claude/skills/` copy reported clean while the authoring path reported four changed
claims. The script's own usage text promises this is "never a silent skip".
Implementation notes:
- Exit-code guidance re-keyed on output as well as code: 0-and-silent passes, 0-with-output is
INFO-only findings, 1 is FAILs, 2 never ran.
- `parse_field_raw()` is line-based and joins continuation lines; `normalize_field_text()`'s
docstring is now true rather than aspirational. A reorder deliberately fires: the two fields share
one parser, and order-insensitivity would mean splitting a prose Description on commas.
- The discarded `show_err` is now surfaced as one whole-check INFO naming both readings.
- `--base-ref=` given empty now beats the env var, as the usage text always claimed.
`validate.sh` gains an ADR-0022 `metadata.version` check at FAIL tier, because any lower tier lets
skill-author Step 4 report done on a file the commit gate then refuses. Its `read` heuristic now
skips here-doc bodies — reflowing the one offending line would have cleared the finding and left
the cause, since every usage() heredoc is one wrap from putting the English verb in column 0.
Impact: provenance tests 73 -> 82, validate tests 64 -> 72. Test 72 previously deleted origin/main
before asserting the override, so it proved the flag works with no default rather than that it beats
one; it now moves origin/main forward first.
Refs: #118
ADR: 0022
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
The #113 sweep rested on CLAUDE.md's premise that rtk either filters or passes through unchanged,
so prefixing is always safe. Measured against rtk 0.42.4, that premise is false for several of the
commands the sweep prefixed, and two skills were left giving wrong answers silently.
Why:
- `rtk git worktree list --porcelain -z` discards both flags and renders its own format. The
`locked`/`lock_reason` fields git-worktrees Step 2 must emit are absent entirely, and paths under
$HOME are abbreviated to `~/`.
- `rtk git branch --list <name>` prints a phantom `* ` line even when nothing matches, so
git-branches' stated ambiguity test — "output from both means the name is ambiguous" — reported
every name as ambiguous. `tag --list` is a clean passthrough, so only one half broke.
- `rtk git diff --name-only`/`--name-status` append a `Changes:` trailer to output documented as
"one per line"; `--word-diff` emits none of the `[-removed-] {+added+}` markers its table
describes; `rtk git log -L` truncates each line at ~72 chars, on the one command whose purpose is
showing line content.
- `rtk git stash pop` prints only `FAILED: git stash pop`, swallowing the conflict diagnostic and
retained-entry message the surrounding prose tells the agent to rely on.
Implementation notes:
- Eleven sites reverted to bare `git`, each carrying its reason inline so the next sweep does not
undo it. `mergetool` and `rebase -i` are reverted on clause 3's interactive limb only: the TTY
defect does not reproduce — rtk filters exactly twelve subcommands and execs the rest — and
ADR-0023 records that measurement rather than a convenient one.
- ADR-0023 states the rule repo-wide with a third clause: a command whose output the skill parses,
or which is interactive, stays bare. `plugins/git/README.md` is reduced to a pointer; its claim
that gitea skills "contain no git/rtk mentions at all" was false, and its citation of
`hard-rules.md` pointed at a file containing no occurrence of "rtk".
- Eight gitea sites swept, all verified byte-identical passthroughs first.
- `scripts/check-rtk-prefix.sh` gates clause 1. Run against main's pre-sweep corpus it reports 99
findings including every gitea site, so it would have caught the drift #113 was filed about.
Impact: the gate covers clause 1 only, in shell-tagged fences and the opening span of Run cells.
Clause 2 is not gateable — "Run `git switch`" and "`git switch` refuses" are the same tokens — and
prose bullets are invisible to it. Both limits are recorded in gates.md rather than left implied.
Refs: #113
ADR: 0023
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
The hook is `entry: bash` with `args: ['-c', <script>]`. pre-commit appends filenames after the
script string, so the first becomes `$0` and never enters `"$@"` — on a single-file commit, the
common case, the loop body never ran and the hook reported Passed having measured nothing.
ADR-0022 leans on this hook as the enforcement for a mandatory `metadata.version`, so the vacuous
green was the whole gate.
Implementation notes:
- An arg0 placeholder absorbs `$0` so every filename lands in `"$@"`.
- Checks now run against the YAML frontmatter block only, extracted with awk. The old
`grep -A10 "^metadata:"` matched a `metadata:` inside a body code fence, spanned past the block
into a following `source:` entry's `version:`, accepted any indentation, and missed a `version:`
more than ten lines in. An unreadable frontmatter block is now an error, never a pass.
- The value is asserted against three-part semver. `write-docs` carried "1.0" through the entire
ADR-0022 retrofit undetected, which a presence-only check cannot catch.
Impact: `tests/test-skill-frontmatter.sh` is the first test this hook has ever had. It drives the
real `entry`/`args` composition read out of the config rather than a copy of the script, which is
the only shape that catches the arg0 bug; against the pre-fix hook it scores 7/20.
gates.md described the hook wrongly in both directions and is rewritten, with a carve-out
explaining why this one stays a shell parser next to the "python3 and PyYAML are hard
requirements" reasoning that argues otherwise.
Refs: #127
ADR: 0022
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
kyberforge's SessionStart hook updates this lockfile automatically
when apm reports the local install behind; it had drifted since
before this branch existed (generated_at predates 598a7c3). Re-ran
apm install to bring the local .claude/ deployment in line with what
the lockfile now expects -- apm audit --ci passes 10/10 clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
Regenerate plugins/*/skills/ from plugins/*/.apm/ after the previous
four commits, via scripts/sync-plugin-content.sh --all. The mirror is
generated output (ADR-0017) that check-plugin-content-sync's pre-push
hook diffs against .apm/; nothing here is hand-edited.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
validate-provenance.sh checked that a sources.md entry was internally
consistent -- slugs resolve, Contributing files exist, back-references
match -- but never whether the asserted contribution was true. A
retrofit once turned an honest hedge into a false confident claim and
every existing check passed it silently.
A literal-filename cross-check (flag a description naming a .md file
absent from Contributing files) was tried and rejected: 3/95 flagged
against the real corpus, all three false positives, and it would not
have caught the actual bug -- the bad description never named a
literal filename. No bash script can verify semantic truth, so the fix
uses what git can reliably detect -- a changed field -- purely as a
trigger for what can verify semantics: the auditor reading the files.
New check 9 flags (INFO only, never FAIL) any Description or
Contributing-files text change against a base ref (default: merge-base
with origin/main, overridable via --base-ref). A slug absent at the
base ref is a creation, not a change, and is not flagged. skill-audit's
rubric now tells the auditor a check-9 INFO means open the named files
and verify by reading, not just relay it. skill-author's retrofit
checklist gained a matching authoring-time guardrail: don't upgrade a
hedge into a confident claim without re-reading the source first.
8 new bats tests (73 total, 0 failures).
Fixes: #118
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
Two bundled fixes across the same nine skills, since both touch the
same files.
Issue #113: skill prose used rtk git and bare git inconsistently for
the same operations, with no stated rule for which applied where.
Executable instructed commands (a dispatch-table "Run" cell, a fenced
code-block procedure, an imperative step) now consistently use rtk
git; illustrative or referential mentions -- naming a flag's behavior,
quoting a doc heading, warning against an anti-pattern -- stay bare
git. Documented in the new plugins/git/README.md, scoped to this
plugin only: gitea-* skills talk to the server over MCP tools and
carry no git/rtk mentions at all.
Also the git-plugin slice of #127: metadata.version added to the
eight skills that lacked it. git-commits already had one and is
untouched.
Fixes: #113Fixes: #127
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
disable-model-invocation and user-invocable are independent Copilot
fields: the first gates whether the runtime auto-selects an agent (i.e.
whether its description is a routing string), the second only gates
manual invocation. An agent can be disable-model-invocation: false plus
user-invocable: false and still be model-routed, so the old bullet
conflated two unrelated contracts under one trigger.
Fixes: #125
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
Only 12 of 39 skills carried metadata.version, and adoption tracked
which plugin a skill lived in rather than any stated rule: core,
gitea and lint were consistent adopters, bin and kyberforge were
consistent non-adopters, git was split with one outlier. There was
no documented convention, and skill-author's own bump logic was
already written as if presence were conditional.
metadata.version is now required on every skill. The 19 skills here
that never carried one (bin, kyberforge, gitea-files) are seeded at
1.0.0, not 0.1.0 -- that value stays reserved for a skill's actual
creation point under skill-author's existing convention. The
skill-frontmatter pre-commit hook now fails a SKILL.md missing the
field, the same class of failure as a missing name/description.
Full rationale in the new ADR. The git-plugin skills that also need
this field follow in the next commit, bundled with issue #113's rtk
normalization since both touch the same files.
Refs: #127
ADR: 0022
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
Retrofits all 39 skills to ADR-0020's description/body context contract, then fixes what six rounds of independent review found in that retrofit — including four ways the hot gate itself failed open.
Closes#99, #107, #108, #110, #111, #114, #115, #120.
## The retrofit (waves 1-5)
| | Start | Now |
|---|---|---|
| Description FAILs (>400 chars) | 26 | **0** |
| Body FAILs (>900 words, body-only) | 9 | **0** |
| Dangling routing targets | 2 | **0** |
| `Kyberforge.CompositionNote` | 10 | **0** |
| Preload tax | 21,005 chars | **~10,500** |
Under the 12,000-char success criterion. Per-wave detail is on #99.
## The review fixes
**The gate failed open four ways, three of them found after the retrofit shipped.** An unrecognised follower token made a dangling target vanish. A skill directory with no `SKILL.md` resolved as a valid target, so a commit could be green locally and red in a fresh clone — three existing fixtures were relying on that, one of which made the install-leak A/B pass vacuously. Then the free-standing `/name` sweep turned out to be gated on the sentence carrying a boundary marker, so route notation in any other sentence was invisible — not an ERROR, not a SUGGESTION, not an INFO — which left the documented "`/name` always blocks" promise false from a second direction. All four fixed and pinned.
**Two checks were silently not running.** `validate-provenance.sh` checks 7-8 were dead across nine skills. Waking them exposed a deeper problem: they assume `Research doc:` names a source index, but 30 of 121 entries point at topic content documents, so every new check-7 INFO was a false positive and check 8 was saved from a false-FAIL flood only by an *unannounced* skip. Checks 7/8 are now scoped to source indexes and every skip announces itself (#121).
**The retrofit's own anti-goal, four times.** ADR-0020 warns that a blunt gate gets satisfied by deleting content rather than relocating it. `diagnose` and `skill-audit` relocated prose and then read it unconditionally; `prototype` and `vale-config` deleted rules outright that survived nowhere. All four addressed.
## Verification
- `bash tests/run-tests.sh --strict` — 24 suites, 0 skipped, 0 failed
- `bash tests/run-bats.sh` — 325 tests, 0 failures
- `pre-commit run --all-files` — 17/17
- `pre-commit run --hook-stage pre-push --all-files` — 16/16, with `apm marketplace check` and `apm pack --check-clean` run against the remote, not skipped
- `scripts/skill-size-check.sh` over all 39 skills — rc 0, 0 ERROR/FAIL, SUGGESTION-only
- Preload tax measured at **10,498 chars**, max description 390 — both inside budget
- Every new test proven non-vacuous by a deliberate mutation of the behaviour it covers
**Per-commit sync, stated accurately:** the ten commits from the latest review round each pass `check-plugin-content-sync` in isolation, verified by checking each out in a detached worktree with a clean between. The earlier gitea window (`dfacf05..bedbd1d`, nine commits) does **not** — its mirror was regenerated in one batch at `bbc7300`. An earlier revision of this description claimed the property held for every commit; it does not, and a bisect through that window lands on a red commit. **Squash-merge** to collapse it, or accept that this range is not bisectable.
## Version bump
Six plugins and the catalog take a **patch**, not a minor. The branch is **89 commits — 40 `fix` / 30 `refactor` / 12 `docs` / 5 `chore` / 2 `test` — zero `feat`, zero `!`, zero `BREAKING CHANGE`** — and adds no skill, agent, command or hook. (Two earlier revisions of this section cited a stale histogram, most recently 78 commits; the figures above are measured at HEAD.) Both rules this repo ships (`forge/references/version-bump.md`, landing in this PR, and `git-commits/references/conventional-commits-spec.md`) make that a patch, and the catalog set is unchanged at 7 entries.
Not settled by that: four published files were removed from the installed tree, three moved, and `caveman` gained `disable-model-invocation`, retiring its old triggers. Under a strict reading those are major-class and currently ship under `refactor:` with no marker. Whether the deployed skill surface is a public contract is written down nowhere — worth deciding, but it outlives this PR.
## Deliberately not in scope
#112 (cherry-pick ownership, now resolved in favour of `git-commits`), #113 (`rtk git` normalisation), #116 (research fan-out), #101 (audit-skill merge), #122 (non-spec skill-root files), #123 (no PRD producer) stay open. #117 is the one worth reading: the contract's remedy is to move prose into `references/`, which is exactly where neither the size gate nor Vale looks — and the blind spot is wider than #117 currently records, since there is no root `.vale.ini` at all, so every ADR, `CONTEXT.md` and `README.md` is unlinted too.
That blind spot let this branch carry two `level: error` `Kyberforge.SentenceOpenerThereIs` violations into `references/` files it created — `provider-adapter-author/references/provider-matrix.md:31` and `agent-audit/references/finding-criteria.md:95`. Both are reworded in `afadaae`, confirmed by routing each file through the audit's own `vale-wrap.sh` (1 error each before, 0 after). Five further occurrences sit in `references/` files already on `main`; those are the pre-existing corpus and stay with #117, which is the real fix.
Also unfixed and not this PR's: `apm install` appends a duplicate `SessionStart` entry to `.claude/settings.json`, so a fresh clone cannot get pre-push green without an edit AGENTS.md warns against. Reproduces identically on `main`.
Co-authored-by: Defame1297 <gitea@rkdr.net>
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/129
Co-authored-by: Claude Code AI - Gitea MCP <claude@noreply.git.dev.rkdr.net>
Co-committed-by: Claude Code AI - Gitea MCP <claude@noreply.git.dev.rkdr.net>
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
