249 Commits

Author	SHA1	Message	Date
Defame1297	8451169d2b	feat(gates): enforce metadata.version bumps on changed skills at pre-push ... check-skill-version-bump fails a push when a skill directory changed against its merge-base with main (tests/ excluded) without a strictly higher metadata.version than main. New, renamed and deleted skills are exempt; every plugin is covered. Recorded as a dated section in ADR-0022 and documented in gates.md. Patch-bumps the 17 skills that changed on this branch without a bump, so the branch passes its own gate. Simplification audit finding 33. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-16 10:09:56 +00:00
Defame1297	ffcbed6c41	fix(tests): replace pipefail-racy echo | grep -q with here-strings ... Why Two suites failed intermittently — tests/test-vale-wrap.sh case 21 and tests/test-check-release-needed.sh cases 4 and 15 — on correct output, and never when run alone. The cause is the `echo "$OUT" | grep -q P` idiom under `set -o pipefail`: grep -q exits as soon as it has an answer, bash's echo can hand a multi-line value to the pipe one line at a time, and a write after the reader is gone kills echo with SIGPIPE. pipefail then reports the writer's death, so output that DID match reads as "no match". Every observed failure had lines after its match; case 15's match is on line 1 of 6, the widest window in that file. Forced with a pause before the writer's last line, the pipe form failed 50 of 50 runs; a here-string, a match on the last line, and the same pipe without pipefail each passed 50 of 50. Unforced the rate is about 1 per 670 suite runs, which is why it read as a flaky gate rather than a bug. The failures at review time are consistent with this, but were not proven to be it: the suite was running while agents edited live config files in place, and a brief change to .vale.ini or .pre-commit-hooks.yaml would produce the same two failures. The race is real and fixed either way. Implementation Notes `grep -q P <<< "$VAR"` has no separate writer process, so there is nothing to race. It is not a retry or a sleep. 121 sites converted across 9 files, three of them scripts rather than tests: new-agent.sh, new-skill.sh and check-executables-allow-sync.sh. None ships via .pre-commit-hooks.yaml, so no external consumer pins them, and all three are single-pipeline checks whose verdict cannot change. Left alone deliberately: 14 sites whose writer is a command, not a shell builtin — they either absorb the writer's status with `|| true` or are python3 and awk, which write once at exit — and one file with no pipefail. `printf '%s'` sites differ from a here-string only by a trailing newline, which no -q verdict on a non-empty pattern depends on. tests/test-no-pipefail-early-exit-grep.sh is a static guard against new occurrences, discovered automatically by run-tests.sh. It only scans files that set pipefail, joins continuation lines, skips comments, and flags only echo/printf writers. Its first case proves the scanner can fail before its second trusts a clean verdict on the tree. A guard covers exactly the spellings its regex models, so the miss surface was measured rather than assumed. Four were found and closed: pipefail declared as `set -o errexit -o pipefail` (where the old pattern required pipefail to follow the FIRST -o, and a file-level miss skips every site in that file); a writer separated from grep by an intermediate stage; a pipeline wrapped on a trailing `|` rather than a backslash; and readers spelled egrep, fgrep, /bin/grep, `command grep` or with an env-var prefix. Segment characters exclude a bare `&` so `echo ok && other | grep -q x`, whose writer is `other`, does not false-fire. Widening surfaced 5 live sites invisible to the original scanner, all in tests/test-apm-current-hook.sh, all `echo "$out" | json_field ... | grep -q`; they are safe today only because json_field is python3, which reads to EOF and writes once. Fixtures go 4 to 12 vulnerable spellings plus near-miss negatives. Two `grep ... | head -1` sites (test-vale-wrap.sh) are the same race with a different early-exiting reader, and are fixed by absorbing the writer. The scanner deliberately does not model `head`, `sed -n 1p` or a bare `read`: most legitimate uses in this tree are already absorbed with `|| true` and the scanner cannot see absorption from pipeline text, so a high false-positive rate would be how this guard gets weakened. Heredoc bodies are scanned as code; none in the tree trips it today. Impact The bug predates the factory-audit merge: every converted site in check-release-needed and case 21 dates to 4d018af and aa8cc22 (2026-08-09). Test suites go 19 to 20. `run-tests.sh --strict` passes 20/20 with 0 skipped, four consecutive runs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD	2026-09-16 09:14:01 +00:00
Defame1297	620f20b0fd	refactor(kyberforge)!: merge skill-audit and agent-audit into factory-audit ... Why The two audit skills carried 1,724 lines of byte-identical duplication: the ADR-0020 boundary resolver (1,061), vale-wrap.sh (526), the Vale style rules (44) and the Contributing-files parser (93). Nothing shared them — they were held in sync by a 413-line pre-push gate and its 797-line test suite. Sync-by-gate had already failed once: at 484357a the two parser copies drifted into different spellings of the bullet loop while a docstring asserted they were identical. That drift was behaviour-neutral and was re-unified by hand at 598a7c3, so the copies were identical at merge time — but nothing had caught it, and the next drift need not be neutral. Implementation Notes Self-containment binds BETWEEN skills, not within one. The agentskills.io spec forbids reaching across skill directories, which is why two separate skills needed embedded copies; two files inside ONE skill may source a third. That is the whole reason the merge removes duplication rather than relocating it. The union of both bodies measured 1,532 words against BODY_MAX_WORDS=900, and only 211 of those words were shared, so SKILL.md is a dispatch body. Step 0 resolves the flow from the target path before any validation, and its table mirrors validate.sh's detection exactly: a directory holding SKILL.md or a SKILL.md file (skill); a *.agent.md, or a .md directly under an agents/ directory (agent); anything else stops without running a validator. Steps 1-3 live in references/skill-flow.md and references/agent-flow.md, and gotchas that apply to one flow live in that flow's file, since it is loaded on every invocation anyway. If validate.sh reports on the other artifact type, the body restarts at Step 0. Named factory-audit rather than forge-audit because forge is a live skill, and a family prefix that matches a live sibling reads as ownership rather than membership. The description carries one arrow per boundary target, because ADR-0020 resolves only the first target after an arrow. It drops the quoted "audit this skill"-style phrases, which restated "audited" in a second register (ADR-0020's duplicate-register rule). 241 characters, Gotchas 16% of the body: no size SUGGESTIONs. The boundary resolver stays embedded in two files rather than imported: a cache-installed plugin cannot read outside its own directory, and the repo-root hook resolves via .pre-commit-hooks.yaml where entry[0] is the only token pre-commit rewrites, so no single file is reachable by both. tests/test-adr0020-contract.sh hashes both copies for byte-identity, and asserts validate.sh sources the resolver and that no third copy exists. The entry scripts classify the target from its resolved parent directory, so a bare agent filename typed inside agents/ works; resolve SCRIPT_DIR CDPATH-safely; and exit 2 when a lib-*.sh is missing, rather than dying with exit 1, the tier the flows relay as real findings. The provenance run functions stash their findings code in KYBERFORGE_PROV_RC and return 0, so validate-provenance.sh calls them UNTESTED. Testing a function's status (`f || RC=$?`) disables errexit for its entire body, and no subshell or `set -e` inside can re-arm it once the call sits in a condition context (measured, both spellings). Their error paths use `exit`, which is unaffected either way; this keeps errexit armed for anything added later. Case 0's readability guard reads the file instead of asking `[[ -r ]]`. `-r` is access(2), which answers yes for uid 0 even on a mode-000 file, and this repo's dev environment is root -- so the guard could never fire where it exists to fire. A read attempt is also the stricter question, catching EIO. This is the reasoning scripts/check-vale-style-sync.sh carried before this commit deleted it; the hazard did not go with it. All three entry scripts are CDPATH-safe, vale-wrap.sh included: both of its cd sites are cleared, the --config resolution and the directory-mirror walk, where an exported CDPATH would otherwise print a decoy path into the -print0 stream and build the mirror from the decoy's files. The two remaining bare cd calls take absolute paths, which CDPATH is never consulted for. Impact BREAKING: skill-audit and agent-audit no longer exist as invocable skills. kyberforge goes to 2.0.0 (catalog 0.4.7). Check logic is unchanged: differential runs of the old and new validators across every skill and agent produced byte-identical stdout, stderr and exit codes, and the reconstructed Python payloads differ only in comments and the references/field-inventory.md -> agent-field-inventory.md rename. One doctrine governs the tiers: exit 0 is audited and clean, exit 1 is audited with findings OR a target present but unreadable, exit 2 is that nothing was audited at all. Edge paths DID change, deliberately (full table in ADR-0025): - a missing target exits 2 (never ran), not 1, under its own "does not exist" message; detection is by path shape, so a shape-matching path that is simply absent used to reach the validator and come back as a FAIL against a file that never existed; - an unshaped target exits 2 under the generic "matches neither" message, and a directory with no SKILL.md under a third, distinct one -- three exit-2 messages, not one; - a dangling symlink or a symlink loop stays exit 1: it is present but broken, which is a finding about the artifact rather than a usage error; - a SKILL.md file path is audited as its skill directory instead of refused; - a .md agent outside an agents/ directory is refused rather than audited; - a missing script library, a missing python3, a missing PyYAML, and no argument at all each exit 2. validate-provenance.sh already exited 2 for the last two; validate.sh now matches it. .pre-commit-hooks.yaml is a published contract consumed by external repos. Both hook IDs and both files: regexes are unchanged; only entry: and description: moved. scripts/check-vale-style-sync.sh (413), scripts/sync-vale-styles.sh (21), tests/test-check-vale-style-sync.sh (797) and agent-audit/scripts/README.md (47) are deleted. The checker made 17 assertions: 6 compared the two Vale copies and are moot; 10 are rehomed into tests/test-vale-wrap.sh (case 0, cases 28-31, and the suite's Vale-absent skip); and the cross-manifest files: agreement check, which selected hooks by entry: and so could not survive both hooks sharing one, is ported as case 33 pairing hooks by id:. Cases 28, 30 and 33 carry mutation self-tests; narrowing the local skill prefilter to 6 of 38 SKILL.md files now fails the suite. Skills go 39 to 38. Pre-push goes 9 repo-authored hooks to 8. ADR: 0025 BREAKING-CHANGE: the skill-audit and agent-audit skills are removed. Both flows are served by factory-audit, which auto-detects whether it was handed a skill directory or an agent file. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD	2026-09-16 09:13:57 +00:00
Defame1297	062ca47a18	docs: correct claims left stale by today's apm-only commits ... A five-agent review of today's seven commits found no executable regressions and no dangling references, but a set of documents still asserting, in present tense, machinery that ADR-0024 and its commits removed. This corrects them in place, keeping the original text as the historical record wherever the repo's amendment convention applies. LESSONS.md: the 2026-06-21 entry prescribed a `claude plugin validate` sweep that now fails on every plugin, so it is marked superseded with the surviving gates named. The 2026-08-09 entry gained a recurrence note: today's manifest deletion broke apm's MCP propagation exactly as that lesson describes, and its prescribed repo-local grep could not have caught it, because `plugin_parser.py` ships in the apm toolchain installed outside this repository. ADR-0019, ADR-0011 and ADR-0021: amendments extended to passages the earlier correction passes stepped over -- a dead native-consumer guard, Consequences bullets still calling for a `plugins/gitea/.mcp.json` that must not be recreated, and a drift-gate list naming a deleted script. ADR-0021's list is down to one gate, not two: `apm audit --ci` never read `description` and was never a drift gate. architecture.md and enrichments.md: the self-containment constraint is restated on its live source, the agentskills.io APM package-mode spec, rather than on Claude Code's plugin cache-install, which ADR-0024 consequence 6 pins as a superseded rationale. releasing.md's pointer to the deleted sync script is rewritten as history. tests/run-bats.sh and scripts/lib/batch-run.sh: comment-only. The `.claude/skills/` exclusion comment claimed a duplication that is not live yet; apm does not strip `tests/`, and the deployed tree is empty of them only because the lockfile still resolves the six dependencies to a pre-ADR-0024 commit carrying the flat mirror. The exclusion is correct but forward-looking, and now says so. SIMPLIFICATION-AUDIT.md: reconciled against what the commits actually did. Two closed findings recorded conclusions that ADR-0024 reversed hours later; findings 1, 3, 31 and 35 carried prescriptions voided the same day; finding 28 is now recorded as having moved backwards, with docs/adr/ measured at +336 lines over the day. The section 1 headline table is re-measured at a6434e0 and labelled with its basis. The ADR-0012 contradiction between finding 2b and section 8 is resolved in 2b's favour after reading the ADR: only finding 24 is governed by it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD	2026-09-14 19:50:23 +00:00
Defame1297	c96ca9ca0d	fix: remove the obsidian MCP server and the unreadable .mcp.json files ... 718c79a deleted every per-plugin .claude-plugin/plugin.json, which reclassified each package from a marketplace plugin to a plain apm package. That silently broke MCP propagation: apm_cli/deps/plugin_parser.py maps a plugin-root .mcp.json into .apm/.mcp.json, and that code path runs only for marketplace plugins. With no manifest, apm never reads the file. Reproduced on ref-pinned consumer clones: at the parent commit a consumer receives the obsidian server, at HEAD it receives none, and on upgrade apm prints "Removed stale MCP server 'obsidian' from .mcp.json". This repo consumes its own plugins through apm (ADR-0018), so the tracked root .mcp.json would have been rewritten to an empty server map on the next lock re-resolve -- silent tool loss plus unexplained working-tree drift. The server is removed entirely rather than relocated to .apm/. It was already a standing question (SIMPLIFICATION-AUDIT finding 37, deferred on 2026-09-13 pending confirmation, now confirmed), and plugins/bin/apm.yml declares dependencies.mcp: [] -- apm's supported mechanism was never used. All seven .mcp.json files go; the root one is apm-generated output and is now gitignored alongside the other install artifacts. ADR-0011's deferred ".mcp.json wiring gap" is moot twice over -- the install route it blocked no longer exists and neither does the file -- and ADR-0018 records why it lost its only worked example of MCP propagation. apm.lock.yaml still carries the server; it clears on the first apm update after this reaches the default branch. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD	2026-09-14 18:09:17 +00:00
Defame1297	061bb3d5b4	docs: correct the apm-only change after a five-agent review ... A five-agent review of 718c79a and d2480b8 found no skill, agent or hook regressions (39 skills before and after) and confirmed both hook removals are genuinely moot -- verified against the tree, not taken on the commit's word. It did find one functional regression (fixed separately) and this documentation drift. Counting errors, all from a git pathspec `*` crossing `/`: - 17 .bats files shipped to consumers is really 10; 17 counted tracked paths merely containing /tests/, one of them a template asset - "roughly 88s off every push" is ~92.4s; 88 omitted validate-plugins - "roughly 70% of each plugin remains live" holds only for kyberforge; the real spread is 44.3% (bin) to 70.6%, now a table - the pre-push enforcement row was half-corrected: 33 entries stood unstruck (now 27) and 14 -> 11 switched counting basis mid-sentence - the root .claude-plugin/plugin.json was described as "kept"; it has never been tracked gates.md said "Ten hooks" above a nine-row table (11 was decremented for one removal, not two), and "both need the claude CLI" for one remaining validator. Its pretty-format-json exclude rationale claimed six alternations expanding to sixteen files in a passage headed "Mind which number you are quoting" -- four alternations, two live files; the two dead ones are dropped from the pattern. check-useless-excludes could not catch this: it only flags an exclude matching nothing at all. ADR-0024 cited ADR-0006 for a patch-bump rule it does not contain and which ADR-0015 explicitly retired; stated apm's marketplace probe order backwards (.claude-plugin/ is the last candidate, not the first, so the earlier .github/plugin/ deletion only demoted resolution); undercounted apm's skill-deploying targets as seven when there are fifteen; and never recorded that validate-plugins was removed. The symlink hedge is resolved: apm_cli/security/gate.py's ignore_non_content() drops symlinks silently on deploy while apm_modules/ materialization dereferences them, so content survives that far and vanishes at install. Accepted with no replacement guard, per decision -- kyberforge/docs/hooks.md previously asserted a guard that had been deleted with its script. Four plugin READMEs still advertised `claude plugin install`; ADRs 0001, 0006, 0013, 0014, 0015 and 0019 described deleted machinery in the present tense, 0019 most consequentially as the live justification for the SessionStart hook's .apm/ path. CONTEXT.md's "apm package" entry forbade "plugin" while using it in its own body, and "Output profile" lost the antecedent for "one catalogue serves both". run-tests.sh gains the .claude/skills/ exclusion run-bats.sh already had. Latent today -- no test-*.sh lives under any .apm/skills/*/tests/ -- but apm now deploys those directories, so one would be discovered twice. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD	2026-09-14 18:09:03 +00:00
Defame1297	718c79af70	chore: drop the flat content mirror and native install support (ADR-0024) ... apm becomes the only supported install path. The flat mirror at each plugin root existed solely so Claude Code's native `claude plugin install` could convention-scan plugin content (ADR-0017). With no native consumers, it cost ~20,000 tracked lines plus ~2,100 lines of sync tooling and ~88s of every push to guard content apm never reads — and its only automated gate, `claude plugin validate --strict`, passes on a plugin with zero content, so it could not detect the defect ADR-0017 was created to fix. Removes the mirror (213 files), the six per-plugin manifest pairs, sync-plugin-content.sh, its 1,289-line test, the orphaned marketplace-plugins.sh, and the check-plugin-content-sync and validate-plugins pre-push hooks. The root `marketplace:` block and .claude-plugin/ catalogue stay: apm's own marketplace consumers read that same file, so `<name>@holocron` short names keep working. tests/run-bats.sh now excludes .claude/skills/. apm installs from .apm/, which carries the tests/ dirs the mirror stripped, so deployed .bats files would otherwise be discovered and double-run. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD	2026-09-14 16:59:42 +00:00
Defame1297	a622200868	docs(pc-skills): trim generic pre-commit boilerplate (finding 38) ... 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	2026-09-13 20:54:17 +00:00
Defame1297	60d3005e67	docs(git): remove stale check-manifests/skill-frontmatter examples ... 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	2026-09-12 22:56:43 +00:00
Defame1297	bde9f7fdd8	chore: fix stale skill-frontmatter and check-manifests references ... 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	2026-09-12 22:13:10 +00:00
Defame1297	6cfc3577e2	docs: trim repeated boilerplate in git, gitea, and bin skills ... 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	2026-09-12 19:48:31 +00:00
Defame1297	f5e4d0d082	docs(git): delete unused git plugin config file and its read steps ... 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	2026-09-12 19:46:28 +00:00
Defame1297	edcc57c0d6	docs: trim skill READMEs and ADR/changelog narration ... 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	2026-09-12 18:38:09 +00:00
Defame1297	c75e4ef4f3	fix(bin): repoint improve-codebase-architecture README's LANGUAGE.md mention ... 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	2026-09-10 19:12:16 +00:00
Defame1297	4f49b2a249	refactor(bin): move non-spec root files into references/ across four skills ... 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	2026-09-09 19:59:02 +00:00
Defame1297	0f2bb242ad	chore(plugins): sync generated content mirrors ... 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	2026-09-09 05:15:53 +00:00
Defame1297	a3e721e937	docs: retire the META.md guidance ADR-0022 overruled, bump touched plugins ... 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	2026-09-09 05:15:41 +00:00
Defame1297	3811f5481b	fix(kyberforge): unblock the scaffold and finish the #125 and ADR-0022 edits ... 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	2026-09-09 05:15:23 +00:00
Defame1297	175ea89c0a	fix(skill-audit): make check 9 reachable, wrap-safe and never silently skipped ... 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	2026-09-09 05:15:05 +00:00
Defame1297	ed8c99efbd	fix(git): stop prefixing rtk where it rewrites the output skills parse ... 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	2026-09-09 05:14:54 +00:00
Defame1297	af8b46cd57	chore(plugins): sync generated content mirrors ... 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	2026-09-07 20:43:51 +00:00
Defame1297	09eea5e7ab	fix(skill-audit): flag a changed provenance claim, not just its shape ... 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	2026-09-07 20:37:03 +00:00
Defame1297	2c6ce438b6	refactor(git): normalize rtk-prefix usage, add metadata.version ... 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: #113 Fixes: #127 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP	2026-09-07 20:36:49 +00:00
Defame1297	ffaa3afb41	fix(agent-audit): remove user-invocable as a hand-invoked marker ... 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	2026-09-07 20:36:34 +00:00
Defame1297	60be7b3232	refactor(skills): mandate metadata.version on every skill's frontmatter ... 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	2026-09-07 20:36:24 +00:00
Claude Code AI - Gitea MCP	598a7c326a	refactor(skills): retrofit the corpus to the ADR-0020 context contract (#129) ... Retrofits all 39 skills to ADR-0020's description/body context contract, then fixes what six rounds of independent review found in that retrofit — including four ways the hot gate itself failed open. Closes #99, #107, #108, #110, #111, #114, #115, #120. ## The retrofit (waves 1-5) | | Start | Now | |---|---|---| | Description FAILs (>400 chars) | 26 | **0** | | Body FAILs (>900 words, body-only) | 9 | **0** | | Dangling routing targets | 2 | **0** | | `Kyberforge.CompositionNote` | 10 | **0** | | Preload tax | 21,005 chars | **~10,500** | Under the 12,000-char success criterion. Per-wave detail is on #99. ## The review fixes **The gate failed open four ways, three of them found after the retrofit shipped.** An unrecognised follower token made a dangling target vanish. A skill directory with no `SKILL.md` resolved as a valid target, so a commit could be green locally and red in a fresh clone — three existing fixtures were relying on that, one of which made the install-leak A/B pass vacuously. Then the free-standing `/name` sweep turned out to be gated on the sentence carrying a boundary marker, so route notation in any other sentence was invisible — not an ERROR, not a SUGGESTION, not an INFO — which left the documented "`/name` always blocks" promise false from a second direction. All four fixed and pinned. **Two checks were silently not running.** `validate-provenance.sh` checks 7-8 were dead across nine skills. Waking them exposed a deeper problem: they assume `Research doc:` names a source index, but 30 of 121 entries point at topic content documents, so every new check-7 INFO was a false positive and check 8 was saved from a false-FAIL flood only by an *unannounced* skip. Checks 7/8 are now scoped to source indexes and every skip announces itself (#121). **The retrofit's own anti-goal, four times.** ADR-0020 warns that a blunt gate gets satisfied by deleting content rather than relocating it. `diagnose` and `skill-audit` relocated prose and then read it unconditionally; `prototype` and `vale-config` deleted rules outright that survived nowhere. All four addressed. ## Verification - `bash tests/run-tests.sh --strict` — 24 suites, 0 skipped, 0 failed - `bash tests/run-bats.sh` — 325 tests, 0 failures - `pre-commit run --all-files` — 17/17 - `pre-commit run --hook-stage pre-push --all-files` — 16/16, with `apm marketplace check` and `apm pack --check-clean` run against the remote, not skipped - `scripts/skill-size-check.sh` over all 39 skills — rc 0, 0 ERROR/FAIL, SUGGESTION-only - Preload tax measured at **10,498 chars**, max description 390 — both inside budget - Every new test proven non-vacuous by a deliberate mutation of the behaviour it covers **Per-commit sync, stated accurately:** the ten commits from the latest review round each pass `check-plugin-content-sync` in isolation, verified by checking each out in a detached worktree with a clean between. The earlier gitea window (`dfacf05..bedbd1d`, nine commits) does **not** — its mirror was regenerated in one batch at `bbc7300`. An earlier revision of this description claimed the property held for every commit; it does not, and a bisect through that window lands on a red commit. **Squash-merge** to collapse it, or accept that this range is not bisectable. ## Version bump Six plugins and the catalog take a **patch**, not a minor. The branch is **89 commits — 40 `fix` / 30 `refactor` / 12 `docs` / 5 `chore` / 2 `test` — zero `feat`, zero `!`, zero `BREAKING CHANGE`** — and adds no skill, agent, command or hook. (Two earlier revisions of this section cited a stale histogram, most recently 78 commits; the figures above are measured at HEAD.) Both rules this repo ships (`forge/references/version-bump.md`, landing in this PR, and `git-commits/references/conventional-commits-spec.md`) make that a patch, and the catalog set is unchanged at 7 entries. Not settled by that: four published files were removed from the installed tree, three moved, and `caveman` gained `disable-model-invocation`, retiring its old triggers. Under a strict reading those are major-class and currently ship under `refactor:` with no marker. Whether the deployed skill surface is a public contract is written down nowhere — worth deciding, but it outlives this PR. ## Deliberately not in scope #112 (cherry-pick ownership, now resolved in favour of `git-commits`), #113 (`rtk git` normalisation), #116 (research fan-out), #101 (audit-skill merge), #122 (non-spec skill-root files), #123 (no PRD producer) stay open. #117 is the one worth reading: the contract's remedy is to move prose into `references/`, which is exactly where neither the size gate nor Vale looks — and the blind spot is wider than #117 currently records, since there is no root `.vale.ini` at all, so every ADR, `CONTEXT.md` and `README.md` is unlinted too. That blind spot let this branch carry two `level: error` `Kyberforge.SentenceOpenerThereIs` violations into `references/` files it created — `provider-adapter-author/references/provider-matrix.md:31` and `agent-audit/references/finding-criteria.md:95`. Both are reworded in `afadaae`, confirmed by routing each file through the audit's own `vale-wrap.sh` (1 error each before, 0 after). Five further occurrences sit in `references/` files already on `main`; those are the pre-existing corpus and stay with #117, which is the real fix. Also unfixed and not this PR's: `apm install` appends a duplicate `SessionStart` entry to `.claude/settings.json`, so a fresh clone cannot get pre-push green without an edit AGENTS.md warns against. Reproduces identically on `main`. Co-authored-by: Defame1297 <gitea@rkdr.net> Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/129 Co-authored-by: Claude Code AI - Gitea MCP <claude@noreply.git.dev.rkdr.net> Co-committed-by: Claude Code AI - Gitea MCP <claude@noreply.git.dev.rkdr.net>	2026-09-01 13:47:46 +00:00
Defame1297	967d3ade25	fix(gitea): document the remaining create/update parameter asymmetries ... 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	2026-08-17 17:29:06 +00:00
Defame1297	4c9d2d7751	fix(gitea): correct which pull_request_write params apply on create ... 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	2026-08-17 16:58:56 +00:00
Defame1297	c7ba3d2ccf	chore(apm): retire skill enumeration from published descriptions ... 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	2026-08-17 12:28:55 +00:00
Defame1297	de84d1b677	chore(apm): give bin a published description that describes it ... 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.	2026-08-17 10:33:25 +00:00
Defame1297	65bac15257	chore(apm): correct git and gitea published descriptions and regenerate ... 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.	2026-08-17 10:13:31 +00:00
Defame1297	54d7bd80ba	docs: rule host built-ins out of the routing target universe ... 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>	2026-08-16 20:45:19 +00:00
Defame1297	75a13c82f6	fix(kyberforge): scope corroboration to a real sentence boundary ... 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>	2026-08-16 20:44:58 +00:00
Defame1297	ede3f06689	fix(kyberforge): restore the authoring rules the ADR-0020 trim dropped ... 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	2026-08-16 19:49:38 +00:00
Defame1297	b0d6d08239	test: pin the nine ADR-0020 gate defects that shipped untested ... 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	2026-08-16 19:49:15 +00:00
Defame1297	f7cc27908c	fix(kyberforge): close the vacuous-green and consumer-resolution defects ... 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	2026-08-16 19:48:56 +00:00
Defame1297	e7ebc667b3	chore(release): kyberforge 1.6.0, marketplace 0.4.2 ... 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.	2026-08-16 16:42:46 +00:00
Defame1297	311e7cd22c	fix(kyberforge): reconcile the authoring rules the ADR-0020 trim left disagreeing ... 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	2026-08-16 16:40:51 +00:00
Defame1297	2540e50fcc	feat(kyberforge): give skill-author a procedure for the #99 retrofit ... 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	2026-08-16 16:40:19 +00:00
Defame1297	a85bdbed42	fix(kyberforge): restore skill-audit's script-failure fallback and E100 diagnostic ... 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	2026-08-16 16:40:00 +00:00
Defame1297	b6e68e9a2b	fix(kyberforge): close the vacuous-pass paths in the ADR-0020 gate scripts ... 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	2026-08-16 16:39:29 +00:00
Defame1297	36ba7a18f8	fix(lint): drop the stale hooks/hooks.json from the content mirror ... 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.	2026-08-14 21:13:25 +00:00
Defame1297	4a5c3c0cff	feat(kyberforge): enforce the ADR-0020 context contract for skills and agents ... Skill name+description pairs are preloaded into every session, costing ~6,200 tokens across 39 skills before any skill is invoked. The authoring rules mandated that growth: skill-author:104 and description-quality.md:21 both required padding, while skill-author:102 (the deflating rule) had no FAIL condition behind it. Gates (blocking, no baseline file): - description 250 chars SUGGESTION / 400 FAIL, measured on the folded YAML value - body-only 600 words SUGGESTION / 900 FAIL, independent of the unchanged whole-file 2770-word / 500-line spec backstop - every boundary-clause routing target must resolve to a real skill or agent; catches skill-improve, neuledge-context and gitea-labels - agents take the description gates but deliberately no body gate; a test pins that absence Vale: DescriptionOpener widened to ^This\b, new CompositionNote rule banning architecture notes from descriptions. 10 hits, 0 false positives. Kyberforge's own four skills retrofitted: descriptions 3,364 -> 938 chars (-72%), bodies 8,306 -> 2,487 words (-70%), all via the apm-workflow dispatch pattern. Fixes the skill-improve dangling route and the agent-author misroute to manual review. Also fixes a pre-existing false positive where any line-initial 'read ' was flagged as interactive input, which had already caused two scripts to be rewritten around it. Refs: ADR-0020	2026-08-14 21:13:13 +00:00
Defame1297	2e395a4efa	chore(apm): sync deployed install after apm update ... 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).	2026-08-14 18:47:33 +00:00
Defame1297	ae178a95a2	fix(kyberforge): detect a single stale package at SessionStart ... 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	2026-08-14 18:31:30 +00:00
Defame1297	b4f5881973	build(apm): pin the obsidian MCP server and release bin 1.1.3 ... 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	2026-08-14 18:31:16 +00:00
Defame1297	3bfdf58960	chore(release): kyberforge 1.5.0, marketplace 0.4.0 ... 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	2026-08-14 17:55:10 +00:00
Defame1297	dee56c506a	feat(kyberforge): refresh the apm install at SessionStart, not at push ... 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	2026-08-14 17:46:38 +00:00
Defame1297	a4a075b07e	chore(apm): regenerate content mirrors ... 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	2026-08-14 14:21:19 +00:00
Defame1297	b8dc400365	fix: reap only our own jobs, and say why a vale probe missed ... 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	2026-08-14 14:21:04 +00:00