8 Commits

Author	SHA1	Message	Date
Defame1297	69119f4754	docs: reconcile the ADRs, gates and audit log with the shipped behaviour ... Why A six-agent review of the two preceding commits found their code sound -- the differential claim holds, the published hook contract is byte-unchanged -- but their prose drifted from it in three ways: statements of fact the code contradicts, markers in a convention this repo does not use, and figures that went stale when the merge changed what they counted. Implementation Notes ADR-0025's edge-path table is rewritten around one stated doctrine: 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. Its old row 1 promised "one generic matches-neither message" for three different inputs; there are three distinct messages, and the missing-path case exited 1 until the preceding commit fixed it. Rows are added for the preflight and CDPATH changes, because a table claiming to enumerate every entry-point behaviour change reproduces its own "an earlier revision of this ADR said they were behaviour-neutral" failure if it omits any. ADR-0025 also gains a Consequences supersession record in ADR-0016's form: partially-superseded entries for 0008, 0014, 0020 and 0021, and explicit "is not superseded" entries with reasoning for the rest. Twelve ADRs are amended and it previously listed none. ADR-0008 moves from an amendment note to partially superseded. Its contract genuinely narrowed -- an agent .md outside an agents/ directory was audited before the merge and is refused now -- and ADR-0020 already recorded that the merge "reopens ADR-0008". Its detector description said "a path under .apm/agents/", the phrasing ADR-0025 rejects as wider than the script and circular; the shipped rule is a .md whose immediate parent is named agents/, at any scope. ADR-0020's amendment claimed the boundary resolver is sourced by validate-provenance.sh. It is not, and never was; only validate.sh sources it, once per mode branch. Three Home-column entries pointed at reference filenames the merge renamed, one of which now resolves to two files because its row covers skills and agents. Five ADRs opened with "Skill renamed per ADR-0025", a form this repo does not use, in the same commit that used the conventional "Amended by ADR-0025" twice. They are normalized. "Renamed" was also wrong: the BREAKING-CHANGE trailer says the skills were removed and their flows merged. SIMPLIFICATION-AUDIT.md had 2026-09-15 notes attached to headlines that were never updated, against its own convention of correcting in place with strikethrough. Every figure here was re-derived at HEAD by command, and several differed from the review's own numbers, so the notes record the basis rather than the result alone. LESSONS.md asserted the two review-time suite failures were the SIGPIPE race. The commit that fixed that race explicitly declined to claim it -- the suite was running while agents edited live config files -- so the hedge is restored. Impact No code, test or configuration change; documentation only. Suites stay 20/20 strict with 0 skipped and 374/374 bats. No gate parses ADR or gates.md content, so nothing here is load-bearing for a hook. 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	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	d42f6368fe	fix(docs): correct claims the first fix round asserted without measuring ... Why: two blind verifiers re-ran the five preceding commits and found four defects of the same class this branch exists to close -- a confidently stated measured claim that does not survive re-measurement -- this time inside the fixes themselves. - AGENTS.md:41 still carried both phrasings c68e864 reports having corrected. `grep -rn repo-defined` returned exactly one hit repo-wide: that line, in the file every session preloads. 4d336bb edited the line directly above it. - ADR-0021 asserted twice, in the section justifying that no gate is added, that the ADR-0020 validators "never open an apm.yml". All three open and yaml.safe_load it (skill-size-check.sh:342, both validate.sh). The conclusion survives -- none reads the description: key, and their globs are SKILL.md and *.agent.md only -- but the stated mechanism is falsified by one grep. - architecture.md said the ADR directory holds 20 numbered ADRs; c7ba3d2 made it 21, and c68e864 audited that file for exactly this class of stale count. The number is dropped rather than corrected: `ls docs/adr/` is already the index, so a count in prose is a second thing to maintain. - gates.md's new three-verdict table said `-> name` promotes an unresolved target to ERROR. Reproduced with fixtures: NAME_HYPH (skill-size-check.sh:543) requires a hyphen, so `-> gitea-prs` is checked and `-> triage` is not extracted at all, and the unicode arrow is never recognised. The SUGGESTION text advises that spelling, so taking its advice can silence the finding. The gap is now documented as a defect; nothing covers it, since the one arrow case in test-adr0020-targets.sh happens to use a hyphenated target. Implementation notes: - AGENTS.md:48's coverage claim is shrunk rather than chased. Restoring six glossary entries did not make it true: 12 more sampled terms are undefined, three of them (trigger/capability/boundary clause) used inside CONTEXT.md itself. It now says CONTEXT.md is the glossary and is not exhaustive. - CONTEXT.md's output profile and near-miss entries are corrected against their sources. The first stated a false exclusion -- .github/plugin/plugin.json IS apm-generated; only the marketplace mirror has no profile. The second inverted its source's referent: description-quality.md defines a near-miss as a query, not a sibling skill. - The strict-mode message named jq, which no suite guards on (`command -v jq` appears nowhere in tests/), while omitting python3/PyYAML, which three do. - README's git and gitea bullets now name git-workflow and gitea-workflow. ADR-0021 leaves README the only inventory and architecture.md now points at it, so the two bullets that were short had to be completed. - ADR-0018's 2026-08-14 correction is marked superseded in place. It asserted machine state in the present tense that its own 2026-08-17 note retracts. - ADR-0021's remaining errors: six files -> four (measured from de84d1b), the wiki description's length 114 -> 96 chars, the codex self-contradiction, the cost argument overstating bumps already owed for any skill addition, and two claims about files this branch went on to edit. - The "15 of 17 suites" figure is restored where I had removed it: it is a dated record of one incident, not a live count, and four sites now describe it the same way. Impact: 16/16 pre-push hooks pass, suite 24 passed 0 skipped 0 failed. No behaviour change; every edit is prose or a comment. Refs: #105 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w	2026-08-17 13:18:55 +00:00
Defame1297	4d336bbf35	docs: stop the preloaded instruction set asserting machine state ... Why: four defects in the files every session pays for, all introduced or left behind by the trim. AGENTS.md told agents the `<plugin>:` form still resolves "because user-scope native installs were left enabled on purpose", and that a working namespaced call "is not something to fix". That premise is false on this machine: installed_plugins.json is empty, no enabledPlugins key exists in ~/.claude.json, and ~/.apm/marketplaces.json is empty. ADR-0018 already reversed itself once on this exact claim (Correction 2026-08-14) using that same enablement as its evidence, so flipping the assertion again would be the third revision in three. Both files now assert nothing about install state at all, which removes the flip-flop surface instead of re-aiming it. The other three are guard-rails whose instruction survived the trim while the caveat that made it safe did not: - The run-tests.sh line omitted --strict, so it named the one invocation that reports SKIPPED rather than failed when a dependency is missing. gates.md records this gate going green having verified 15 of 17 suites on a vale-less PATH. .pre-commit-config.yaml:70 already uses --strict for that reason. - The .claude/settings.json prohibition lost its ADR-0019 exception, so an agent applying it literally would strip apm's own merged SessionStart entry and create the drift the rule exists to prevent. - LESSONS.md still routed graduated rules to CONTEXT.md's Principles section, which this branch deleted. Implementation notes: the six terms the trim dropped while AGENTS.md still claimed CONTEXT.md glosses everything -- authoring root, content mirror, apm package, output profile, near-miss, vacuous green -- are restored as one-line entries per CONTEXT-FORMAT.md, sourced from architecture.md, gates.md and skill-audit's description-quality.md rather than reworded. ADR-0018 gets a third dated note recording the observation and the fact that the state has now been described two ways, and its stale user-scope inventory is replaced by a pointer to it; the decision it records is untouched. LESSONS.md:3 carried the identical stale claim as :5 and is fixed with it. Impact: preloaded context is now free of assertions about machine state. Refs: #105 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w	2026-08-17 12:28:30 +00:00
Defame1297	c9fe2e8ab2	docs: correct the namespace claim and record the hook fixes ... AGENTS.md and CONTEXT.md asserted that the `<plugin>:<skill>` form "no longer resolves here". It does: ~/.claude.json still enables core, git, gitea, kyberforge and lint at user scope, which ADR-0018 left in place deliberately. Both names are live at once, so a working `gitea:gitea-prs` is the user-scope copy answering — not evidence that the apm install is broken and not something to "fix". ADR-0018 contradicted itself on this, claiming every namespaced reference went stale while its own "User scope is untouched" consequence said otherwise; recorded as a dated correction alongside the existing one. Bare names stay the documented default. Five stale pre-push hook counts updated for the new check-executables-allow-sync gate: 13 -> 14 repo-defined hooks, 15 -> 16 reported by pre-commit, eleven -> twelve passing offline. The gate reads two local manifests and makes no network call, so the SKIP pair for offline pushes stays exactly two. "Four pre-push hooks shell out to apm" is unchanged and still correct — the new hook parses YAML directly. ADR-0019 gains the timeout arithmetic, the singular/plural failure and why mocking every apm call hid it, and a consequence recording that the trust gate is keyed on version rather than content: an edit to a hook script landing on main deploys and executes unattended on the next session start, since the dependency is unpinned and the hook runs `apm update --yes`. That is accepted, not overlooked, but it is why the gate should not be read as a supply-chain control. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT	2026-08-14 18:31:42 +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	2e8732a8e5	build(apm): consume holocron plugins through apm instead of plugin install ... Why: The repo published apm packages but consumed them the old way — `claude plugin install <name>@holocron`, six plugins enabled per project. Dogfooding stopped one layer short of the install tooling kyberforge itself ships. Implementation notes: - Root apm.yml declares the six packages as dependencies.apm git+path objects against the holocron remote. Object form over `<name>@holocron` aliases on purpose: an alias first needs `apm marketplace add`, which writes to ~/.apm/marketplaces.json — user scope, absent on a fresh clone. Unpinned against the default branch, matching the autoUpdate the native install had. - apm.lock.yaml is committed; .claude/skills/, .claude/agents/ and apm_modules/ are gitignored regenerable install output. Committing the deployed skills would add a third mirror of content ADR-0017 already governs two copies of. - .mcp.json is generated by apm from plugins/bin/.mcp.json, so the obsidian MCP server survives the switch. - .claude/settings.json is reduced to {"hooks": {}}. apm replays the install into a scratch tree and diffs, so any repo-owned key there is permanent drift that fails apm-audit-ci. Nothing was lost: enabledPlugins was empty after the uninstall and the only hooks entry was PreToolUse: []. - tests/run-bats.sh and tests/run-tests.sh exclude apm_modules/. It holds a full copy of every plugin, and a copied .bats file resolves its helpers against the dependency root rather than this repo — 334 tests, 167 failures before the exclusion. Impact: Skills are now unnamespaced — `git-commits`, not `git:git-commits` — because apm deploys plain project skills with no plugin to prefix. AGENTS.md, CONTEXT.md and docs/spec/architecture.md are updated accordingly. Root apm.yml now declares dependencies, which arms apm-audit-ci's lockfile-exists check for the root manifest. External consumers are unaffected: the marketplace manifests are untouched and `apm pack --check-clean` stays clean. Project scope only. ADR: 0018 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT	2026-08-14 17:15:17 +00:00