Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs: dedupe .apm/-mirror and apm.lock/SessionStart restatements (finding 29)

Browse Source 
README and AGENTS.md each fully restated the "edit .apm/, never the
mirror" rule and the apm.lock/SessionStart mechanism instead of linking
to their canonical sources (architecture.md, ADR-0019).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
This commit is contained in:
Defame1297
2026-09-14 07:15:19 +00:00
parent e2e957efdd
commit afa7187d33
3 changed files with 7 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
README.md
View File

@@ -59,9 +59,7 @@ pre-commit install -t pre-commit -t commit-msg -t pre-push
## Keeping the install current
The six dependencies in root `apm.yml` are unpinned against the default branch, so deployed skills go stale whenever anyone merges. kyberforge ships a `SessionStart` hook that runs `apm outdated` at startup (~0.7s) and, when something is behind, runs `apm update --yes` and asks the host to re-scan skills (~10.4s).
That rewrites `apm.lock.yaml` — an unexplained modification to it after opening a session is expected, not a bug. Commit or discard it deliberately.
The six dependencies in root `apm.yml` are unpinned against the default branch, so deployed skills go stale whenever anyone merges. kyberforge's `SessionStart` hook keeps the install current automatically on launch, rewriting `apm.lock.yaml` in the process — an unexplained modification to it after opening a session is expected, not a bug; commit or discard it deliberately. Mechanism and rationale: `docs/adr/0019-session-start-hook-keeps-the-apm-install-current.md`.
Note the difference between the two commands:
@@ -98,11 +96,9 @@ See [`docs/spec/gates.md`](docs/spec/gates.md) for what each hook enforces and w
## Editing plugin content
`plugins/<name>/.apm/` is the only hand-edited source for plugin content — skills, agents, commands, instructions, extensions, and hooks. The flat `plugins/<name>/{skills,agents,commands,instructions,extensions}/` directories, the merged `hooks/hooks.json`, and every `plugin.json` / `marketplace.json` manifest are generated. Nothing labels a generated file as generated, so check the path before you edit; an edit to the mirror is discarded by the next sync and reported as drift by the `check-plugin-content-sync` pre-push hook.
`plugins/<name>/.apm/` is the only hand-edited source for plugin content — the flat mirror directories and every `plugin.json` / `marketplace.json` manifest are generated, discarded by the next sync, and reported as drift by `check-plugin-content-sync` if hand-edited instead. Hand-authored material that is not an `.apm/` primitive (`README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json`) lives at the plugin root instead and is untouched by the sync.
Hand-authored material that is *not* an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json` — lives at the plugin **root** and is untouched. Never place such a file inside a mirrored directory: the sync removes the destination before every copy, so it is deleted with no drift report.
Full detail in [`docs/spec/architecture.md`](docs/spec/architecture.md).
Full model, including what's exempt and why: [`docs/spec/architecture.md`](docs/spec/architecture.md).
## For external consumers