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
This commit is contained in:
@@ -61,7 +61,9 @@ was stale the moment the switch landed; `AGENTS.md` and `CONTEXT.md` are updated
|
||||
form still resolves for anyone installing holocron natively, so skill bodies written for both
|
||||
audiences should name the bare skill.
|
||||
|
||||
**apm owns `.claude/settings.json`.** `apm audit --ci` replays the install into a scratch tree and
|
||||
**apm owns `.claude/settings.json`.** (ADR-0019 supersedes the "exactly `{"hooks": {}}`" claim
|
||||
below — once a package ships a hook, apm merges it into that file and the merged entry is apm's own
|
||||
output. The rule that nothing repo-authored goes in the file is unchanged.) `apm audit --ci` replays the install into a scratch tree and
|
||||
diffs it against the worktree. apm's hook integrator writes that file, so the replay expects
|
||||
exactly what apm would have written — `{"hooks": {}}` — and any repo-owned key in it is permanent
|
||||
drift that fails the `apm-audit-ci` pre-push hook. Verified both directions: with the pre-existing
|
||||
@@ -93,9 +95,16 @@ apm's "contributed no entries to claude settings; skipped" warning on `kyberforg
|
||||
accurate and harmless.
|
||||
|
||||
**A `.apm/` edit now needs a round trip.** The dependency resolves from the remote, so an edit is
|
||||
invisible to the running session until it is pushed and `apm install` re-runs. Under the native
|
||||
install with `autoUpdate` the shape was the same; it is more noticeable now because `apm install`
|
||||
is a manual step where marketplace auto-update was not.
|
||||
invisible to the running session until it is pushed and the install is refreshed. Under the native
|
||||
install with `autoUpdate` the shape was the same; it was more noticeable here at first because the
|
||||
refresh is a manual step where marketplace auto-update was not — ADR-0019 automates it at
|
||||
`SessionStart`.
|
||||
|
||||
**Correction (2026-08-14): the refresh command is `apm update`, not `apm install`.** An earlier
|
||||
revision of this paragraph named `apm install`, which is wrong: `apm install` deploys from the
|
||||
pinned `resolved_commit` in `apm.lock.yaml` and does not re-resolve refs (`apm install --force`
|
||||
documents this explicitly — "does NOT refresh refs; use 'apm update' for that"). Running it after a
|
||||
merge redeploys the same content and reports success.
|
||||
|
||||
**User scope is untouched, deliberately.** `bin@holocron`, `gitea@holocron`, and a stale
|
||||
`hello-world@holocron` remain natively installed at user scope, and every project other than this
|
||||
|
||||
Reference in New Issue
Block a user