AGENTS.md

@@ -31,7 +31,7 @@ This repo dogfoods its own plugins. Before shelling out to git, gitea, or lint t
 - Vale prose linting → `vale-config` / `vale-run`
 - This repo's own AGENTS.md → `agentsmd-author` / `agentsmd-audit`
 
-Names are **unnamespaced**. Under the old `claude plugin install` these were `git:git-commits`, `kyberforge:skill-audit`, and so on; `apm install` deploys each skill to `.claude/skills/<name>/` as a plain project skill, which has no plugin prefix to carry. The `<plugin>:` form no longer resolves here — it still does in any project that installs holocron natively, so a skill body written for both audiences should name the bare skill. Same for agents: `git-orchestrate`, not `git:git-orchestrate`.
+Use the bare, **unnamespaced** names above. Under the old `claude plugin install` these were `git:git-commits`, `kyberforge:skill-audit`, and so on; `apm install` deploys each skill to `.claude/skills/<name>/` as a plain project skill, which has no plugin prefix to carry. The `<plugin>:` form has not stopped resolving here, though — `~/.claude.json` still enables `core`, `git`, `gitea`, `kyberforge`, and `lint` at **user** scope, and ADR-0018 left those native installs in place on purpose, converting them being a separate decision with a blast radius beyond this repo. Every skill is therefore live under both names right now, and a working `gitea:gitea-prs` is the user-scope copy answering — not evidence that the apm install or this file is broken, and not something to "fix". Prefer the bare name anyway: apm deploys it, an external consumer installing holocron through apm gets it, and it is the form that survives those user-scope installs eventually being converted. The namespaced form also still resolves in any project that installs holocron natively, so a skill body written for both audiences should name the bare skill. Same for agents: `git-orchestrate`, not `git:git-orchestrate`.
 
 Fall back to raw shell only when no skill covers it.
 
@@ -40,7 +40,7 @@ Fall back to raw shell only when no skill covers it.
 - Run `apm install` to deploy this repo's own skills and agents into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, not authoring source — `plugins/<name>/.apm/` remains the only place to edit. The six dependencies in root `apm.yml` resolve from the holocron **remote**, unpinned against the default branch, so a `.apm/` edit is not visible to the running session until it is pushed and `apm update` re-runs (`apm install` deploys from `apm.lock.yaml` and does not re-resolve refs). Needs the network, and needs `apm_modules/` (which it materializes) left gitignored. `apm install` also configures the `obsidian` MCP server into the repo's `.mcp.json`, carried over from `plugins/bin/.mcp.json`.
 - Do not add repo-owned keys to `.claude/settings.json`. apm treats that file as its own deployed artifact: `apm audit --ci` replays the install into a scratch tree and diffs, so anything apm would not have written there — an `enabledPlugins` block, a real `hooks` entry — is permanent drift that fails the `apm-audit-ci` pre-push hook. Its committed content is whatever apm last wrote — `{"hooks": {}}` until kyberforge's `SessionStart` hook lands there, after which the merged hook entry is apm's output and belongs in the commit (ADR-0019). What does not change is that nothing repo-authored goes in the file. A hook you want in this repo is authored in `plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written here. Machine-specific settings go in the gitignored `.claude/settings.local.json`, which apm does not deploy and the replay does not compare; shared enforcement belongs in `.pre-commit-config.yaml`.
 - Keeping the install current is automatic but not free. Because the six dependencies are unpinned, 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`, so an unexplained modification to it after opening a session is expected, not a bug — commit or discard it deliberately. Note `apm install` alone will **not** pick up remote changes; it deploys from the lock. `apm update` is the command that re-resolves refs.
-- Install git hooks via `pc-run`, wiring all three stages — this repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain install silently skips `commit-msg` (Conventional Commits) and `pre-push` (the 13-hook gate described below).
+- Install git hooks via `pc-run`, wiring all three stages — this repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain install silently skips `commit-msg` (Conventional Commits) and `pre-push` (the 14-hook gate described below).
 - Install the `apm` CLI — four pre-push hooks shell out to it: `apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`, and `check-plugin-content-sync` (via `scripts/sync-plugin-content.sh`, which wraps `apm pack`). `apm-marketplace-check` and `apm-pack-check-clean` are bare `apm …` hook entries and `apm-audit-ci` is a `bash -c` loop calling `apm` once per package, so without it the push dies with an unhelpful "command not found". Use `apm-install`, or `curl -sSL https://aka.ms/apm-unix | sh`; verify with `apm --version`.
 - Install `jq` — required by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh`, both pre-push. These at least fail loudly (`Error: jq is required but not installed`).
 - Install the `vale` binary — required by the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks. Their `files:` patterns are `.apm/`-scoped: `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` and `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$`. Only the authoring source triggers them — a `SKILL.md` in the generated mirror matches neither pattern, so prose findings surface only when you edit the file you are supposed to be editing. Without the binary the hooks fail with a bare "command not found" and no install pointer. `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or see https://vale.sh/docs/vale-cli/installation/. No `vale sync` needed — the `Kyberforge` styles are committed under `plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/assets/vale/styles/`, not downloaded packages (see ADR-0014).
@@ -48,10 +48,10 @@ Fall back to raw shell only when no skill covers it.
 - Run `bash tests/run-tests.sh` before considering any change done — it runs every `test-*.sh` script in the repo plus the bats suite (`--bats-only` for just bats). First run auto-initializes the bats submodules; no manual `git submodule update` needed.
 - A suite that exits 77 because a dependency is missing is reported as SKIPPED, and does **not** fail an ad-hoc run. The pre-push hook invokes the same script as `--strict` (`RUN_TESTS_STRICT=1` is equivalent), where a skip **does** fail the push: at pre-push a skip means one of the dependencies above is absent on this machine, so the gate would otherwise report success having run fewer suites than it appears to. Without vale, for instance, three suites skip (`test-check-vale-style-sync.sh`, `test-vale-hooks-consumer.sh`, `test-vale-wrap.sh`) and the strict failure names each one and what to install.
 - `tests/run-bats.sh` derives the set of `.bats` files it expects from `git ls-files`, so a `.bats` file deleted from the worktree but still tracked in the index fails the run rather than silently shrinking the suite. Remove one with `git rm` (or stage the deletion) when the removal is intentional; an untracked new `.bats` file is picked up and needs no ceremony. Both discovery walks (`tests/run-bats.sh` and `tests/run-tests.sh`) exclude `apm_modules/`: `apm install` materializes a full copy of every plugin there, and running a dependency's copy of a `.bats` file breaks its relative path to the bats helpers — 167 spurious failures before the exclusion landed.
-- Pushing runs 13 repo-defined pre-push hooks, not just the test suite — `run-tests` and `check-manifests`, plus generated-content drift gates (`check-plugin-content-sync`, `check-marketplace-mirror-sync`, `check-vale-style-sync`, `check-scope-walkup-sync`), artifact validators (`check-apm-agents-valid`, which runs agent-audit's `validate.sh` over every real `plugins/*/.apm/agents/*.agent.md`), apm's own gates (`apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`), host validators (`validate-plugins`, `validate-marketplace`, both needing the `claude` CLI), and `check-release-needed`. Run `pre-commit run --hook-stage pre-push --all-files` locally — one command, the whole gate. That command reports **15**, not 13: pre-commit's own `meta` hooks, `check-hooks-apply` and `check-useless-excludes`, declare no `stages:` and so run at every stage including this one.
+- Pushing runs 14 repo-defined pre-push hooks, not just the test suite — `run-tests` and `check-manifests`, plus generated-content drift gates (`check-plugin-content-sync`, `check-marketplace-mirror-sync`, `check-vale-style-sync`, `check-scope-walkup-sync`, `check-executables-allow-sync`), artifact validators (`check-apm-agents-valid`, which runs agent-audit's `validate.sh` over every real `plugins/*/.apm/agents/*.agent.md`), apm's own gates (`apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`), host validators (`validate-plugins`, `validate-marketplace`, both needing the `claude` CLI), and `check-release-needed`. `check-executables-allow-sync` is the odd one in that first group — it guards a silent failure rather than drift in generated text. apm gates a package's `hooks/` and `bin/` on an exact `<package>#<version>` lookup in root `apm.yml`'s `executables.allow`, with no wildcard and no version-less form, so bumping `plugins/kyberforge/apm.yml`'s `version:` without bumping the key errors nowhere: the entry simply stops matching, kyberforge's `SessionStart` hook stops deploying, and the install goes quietly stale — the failure ADR-0019 records as live. Run `pre-commit run --hook-stage pre-push --all-files` locally — one command, the whole gate. That command reports **16**, not 14: pre-commit's own `meta` hooks, `check-hooks-apply` and `check-useless-excludes`, declare no `stages:` and so run at every stage including this one.
 - `apm-audit-ci` runs `apm audit --ci` once per manifest — the root one and each of the six plugin packages — because the root-only invocation audits the marketplace manifest and **nothing else**, and `apm-pack-check-clean` does not parse plugin `dependencies:` blocks either (verified: a malformed one passes `apm pack --check-versions --check-clean --dry-run` and fails `apm audit --ci` in that package's directory). It verifies two things and claims no more: each `apm.yml` parses as a valid APM manifest, and any package declaring dependencies has a consistent `apm.lock.yaml`. It does **not** enforce an org policy — apm discovers one from the git remote and only understands github.com and Azure DevOps, so against this repo's self-hosted Gitea remote it prints `No org policy found at unknown; enforcement skipped`. Do **not** "fix" that with `policy.fetch_failure_default: block` in `apm.yml`: it was tested and rejected, because with no reachable policy source it makes the hook exit 1 on every push forever.
 - `check-apm-agents-valid` derives its expected agent-file set from `git ls-files` (same pattern as `tests/run-bats.sh`), so an agent file deleted from the worktree but still tracked fails the run, and discovering zero agent files is an error rather than a pass. An untracked new agent file is still validated — the derivation is one-directional on purpose, so uncommitted work is not blocked but also cannot bypass the gate.
-- **Two** pre-push hooks need the network, for one shared reason: root `apm.yml`'s `marketplace.packages[]` contains exactly one remote entry (`mattpocock-skills`, `source: mattpocock/skills`), and resolving it needs a `git ls-remote`. `apm-marketplace-check` resolves every entry and is `always_run`, so it fails with `No cached refs (offline)`. `apm-pack-check-clean` (`apm pack --check-versions --check-clean --dry-run`) re-resolves the same entry and fails with `Error: Git network timeout during ls-remote`. Pinning the entry to an exact version does **not** remove the call — an exact pin still ls-remotes. `--offline` rescues neither. To push without a network, skip both using pre-commit's own mechanism: `SKIP=apm-marketplace-check,apm-pack-check-clean git push`. Skip those two alone — verified under `unshare -rn`, the other eleven pre-push hooks pass offline because they are real local checks, and adding one of them to `SKIP` disarms it silently. `apm-audit-ci` calls `apm` too but stays local: its org-policy discovery resolves nothing on this remote before any network call, so it does not join the pair above.
+- **Two** pre-push hooks need the network, for one shared reason: root `apm.yml`'s `marketplace.packages[]` contains exactly one remote entry (`mattpocock-skills`, `source: mattpocock/skills`), and resolving it needs a `git ls-remote`. `apm-marketplace-check` resolves every entry and is `always_run`, so it fails with `No cached refs (offline)`. `apm-pack-check-clean` (`apm pack --check-versions --check-clean --dry-run`) re-resolves the same entry and fails with `Error: Git network timeout during ls-remote`. Pinning the entry to an exact version does **not** remove the call — an exact pin still ls-remotes. `--offline` rescues neither. To push without a network, skip both using pre-commit's own mechanism: `SKIP=apm-marketplace-check,apm-pack-check-clean git push`. Skip those two alone — verified under `unshare -rn`, the other twelve pre-push hooks pass offline because they are real local checks (`check-executables-allow-sync` landed after that run, but reads two local manifests and makes no network call), and adding one of them to `SKIP` disarms it silently. `apm-audit-ci` calls `apm` too but stays local: its org-policy discovery resolves nothing on this remote before any network call, so it does not join the pair above.
 - Author commits with `git-commits` — it validates Conventional Commits (enforced at `commit-msg`) for you.
 
 ## Key documents

CONTEXT.md

@@ -33,10 +33,10 @@ The deployable unit in the plugin marketplace. A plugin bundles one or more skil
 A Git repository with a `marketplace.json` manifest listing installable plugins. No backend, registry, or SaaS required — the Git repo is the marketplace. This repo is the `holocron` marketplace. The manifest at `.claude-plugin/marketplace.json` (read by both Claude Code and Copilot CLI) is **compiled output** of `apm pack`, generated from the root `apm.yml`'s `marketplace:` block (owner, build/output config, versioning strategy, and the `packages:` list of installable plugins) — it is not hand-edited. See ADR-0015. `.github/plugin/marketplace.json` is Copilot CLI's legacy manifest path; apm has no output profile for it (only `claude` and `codex`, and `codex`'s is a differently-shaped file at `.agents/plugins/marketplace.json`), so `scripts/sync-marketplace-mirror.sh` keeps it byte-identical to `.claude-plugin/marketplace.json`, checked at pre-push. Each listed package's `source:` still points at that plugin's own `plugins/<name>/` root, not at an `apm pack` build artifact — which is why that root also carries the flat `agents/`/`skills/`/`commands/`/`hooks/hooks.json` content mirror described under "Plugin" (ADR-0017): without it, an install from this marketplace finds a valid manifest but no discoverable content.
 
 ### apm-consumed install
-How this repo installs its own plugins, as of 2026-08-14: not `claude plugin install <name>@holocron`, but six `dependencies.apm` entries in the root `apm.yml`, each a `git:`/`path:` object against the holocron remote, deployed by `apm install` into `.claude/skills/` and `.claude/agents/`. Project scope only — nothing is installed at user scope, so the switch is contained to this repo and any other repo opts in by declaring its own dependencies. The git+path object form is deliberate over the shorter `<name>@holocron` marketplace alias: an alias must first be registered with `apm marketplace add`, which writes to `~/.apm/marketplaces.json` (user scope, outside the repo), whereas the object form needs nothing beyond the committed manifest and so survives a fresh clone.
+How this repo installs its own plugins, as of 2026-08-14: not `claude plugin install <name>@holocron`, but six `dependencies.apm` entries in the root `apm.yml`, each a `git:`/`path:` object against the holocron remote, deployed by `apm install` into `.claude/skills/` and `.claude/agents/`. Project scope only — apm installs nothing at user scope, so the switch is contained to this repo and any other repo opts in by declaring its own dependencies. The git+path object form is deliberate over the shorter `<name>@holocron` marketplace alias: an alias must first be registered with `apm marketplace add`, which writes to `~/.apm/marketplaces.json` (user scope, outside the repo), whereas the object form needs nothing beyond the committed manifest and so survives a fresh clone.
 
 Four consequences, each load-bearing:
-- **Skills lose their namespace.** apm deploys plain project skills, so `git:git-commits` is now `git-commits`. The `<plugin>:` form does not resolve in this repo. It still does wherever holocron is installed natively, so cross-audience skill bodies should use the bare name.
+- **Skills gain an unnamespaced name.** apm deploys plain project skills, so `git:git-commits` also answers to `git-commits`. The `<plugin>:` form has not stopped resolving here: `~/.claude.json` still enables `core`, `git`, `gitea`, `kyberforge`, and `lint` at user scope, which ADR-0018 left in place deliberately — converting them is a separate decision with a blast radius beyond this repo. Until it is taken, every skill is live under two names, which is the same "present twice under two names" outcome ADR-0018's own "Alternatives considered" rejected for *keeping both install paths* — reached here by leaving user scope alone rather than by adopting it as the install model. Write the bare name regardless: apm deploys it, and a repo consuming holocron through apm gets only that form. The namespaced form still resolves wherever holocron is installed natively, so cross-audience skill bodies should use the bare name.
 - **apm owns `.claude/settings.json`.** `apm audit --ci` (an `apm-audit-ci` pre-push hook) replays the install into a scratch tree and diffs it against the worktree, so any key apm would not have written is permanent drift. Committed content is exactly `{"hooks": {}}`; repo-owned settings have nowhere to live in that file.
 - **Install output is gitignored.** `.claude/skills/`, `.claude/agents/`, and `apm_modules/` are all regenerated by `apm install`. `apm.lock.yaml` and the generated `.mcp.json` are committed. Committing the deployed skills would add a third mirror of the same content to the two ADR-0017 already governs.
 - **Test discovery must skip `apm_modules/`.** It holds a full copy of every plugin, `.bats` files included; both `tests/run-bats.sh` and `tests/run-tests.sh` exclude it.

docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md

@@ -54,12 +54,23 @@ Three sub-decisions inside that:
 
 ## Consequences
 
-**Skills lose their namespace.** apm deploys plain project skills, so `git:git-commits` is now
-`git-commits` and `kyberforge:skill-audit` is `skill-audit`. This is not configurable — a project
-skill has no plugin to prefix. Every `<plugin>:<skill>` reference in the repo's own instructions
-was stale the moment the switch landed; `AGENTS.md` and `CONTEXT.md` are updated. The namespaced
-form still resolves for anyone installing holocron natively, so skill bodies written for both
-audiences should name the bare skill.
+**Skills gain an unnamespaced name.** apm deploys plain project skills, so `git:git-commits` also
+answers to `git-commits` and `kyberforge:skill-audit` to `skill-audit`. This is not configurable —
+a project skill has no plugin to prefix. `AGENTS.md` and `CONTEXT.md` are updated to name the bare
+form, which is what apm deploys and the only form a repo consuming holocron through apm gets.
+
+**Correction (2026-08-14): the namespaced form did not stop resolving.** An earlier revision of
+this consequence said every `<plugin>:<skill>` reference "was stale the moment the switch landed",
+and `AGENTS.md`/`CONTEXT.md` were written to match. That contradicts the "User scope is untouched,
+deliberately" consequence below, and the contradiction resolves against it: `~/.claude.json` still
+enables `core`, `git`, `gitea`, `kyberforge` and `lint` at user scope, so both names are live at
+once and a working `gitea:gitea-prs` is the user-scope copy answering. That doubling is the same
+"present twice under two names" outcome the "Keeping both install paths" alternative was rejected
+for — reached by leaving user scope alone rather than by adopting it, which is why it is a
+consequence to record rather than a decision to revisit. Prefer the bare name regardless: it
+survives those user-scope installs eventually being converted, and the namespaced 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`.** (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

docs/adr/0019-session-start-hook-keeps-the-apm-install-current.md

@@ -70,8 +70,31 @@ this machine still has it open.
 immediately, since bumping kyberforge to 1.5.0 required editing the key in the same commit. A
 kyberforge version bump makes the entry stop matching, the
 gate blocks the hook, and the install silently stops refreshing — the exact failure this ADR exists
-to end, reintroduced through the mechanism meant to secure it. The `executables:` block carries a
-comment saying to check it first when skills go stale after a release.
+to end, reintroduced through the mechanism meant to secure it.
+
+Matching is an exact dictionary lookup on the composed `name#version` string
+(`apm_cli/security/executables.py`, `is_package_approved`), so there is no wildcard or
+version-less key that would sidestep this — the key has to be edited on every bump, and the
+question is only what catches a missed edit. A comment in the `executables:` block is not enough:
+this repo gates generated-content drift, marketplace mirror drift and vale style drift
+deterministically, and a silent-staleness failure is strictly worse than any of them. So
+`scripts/check-executables-allow-sync.sh` runs at pre-push, parsing `version:` out of
+`plugins/kyberforge/apm.yml` and asserting root `apm.yml` carries the matching
+`kyberforge#<version>` key. The comment stays as the human-facing pointer; the hook is what
+actually holds. It parses with PyYAML where importable and falls back to a two-shape scan
+otherwise, so a missing pip package cannot become the thing that blocks every push.
+
+**Trust is keyed on the version, not on the content.** `kyberforge#1.5.0` approves whatever
+`check-apm-current.sh` contains at the moment it is fetched, not the bytes that were reviewed when
+the key was written. Because the dependency is unpinned against the default branch and the hook
+runs `apm update --yes` unattended, an edit to that script landing on `main` deploys and executes
+on every contributor's machine at their next session start, with no second approval prompt and no
+diff shown. The trust gate constrains *which package* may ship an executable; it does not constrain
+what that executable does between version bumps. That is an accepted property of this design rather
+than an oversight — the remote is self-hosted, push access to `main` is already sufficient to
+change any skill body an agent will follow — but it is the reason the gate should not be read as a
+supply-chain control. Pinning each dependency to a `ref:` is what would make it one, and ADR-0018
+defers that until per-package release tags exist.
 
 **A referenced hook script must be addressed at its `.apm/` path.** apm resolves
 `${CLAUDE_PLUGIN_ROOT}/...` against the installed package root, and `apm pack` keeps only `*.json`
@@ -84,7 +107,30 @@ A test pins the reference.
 
 **Session startup gets slower when the install is stale.** Measured: ~0.7 s for the `apm outdated`
 check when everything is current, ~10.4 s when six packages are behind and the refresh runs. The
-hook declares `timeout: 320` to cover a cold multi-package fetch.
+hook declares `timeout: 380` to cover a cold multi-package fetch. That number is not free-standing:
+the script imposes its own `timeout 60` on `apm outdated` and `timeout 300` on `apm update`, so the
+host-side timeout has to exceed their sum or the host kills the hook mid-update and leaves
+`.claude/skills/` half-deployed with no notice emitted. An earlier revision declared `320`, which
+was below the 360 s the script can legitimately take. A test asserts the invariant rather than the
+literal — it parses every `timeout N` out of the script, sums them, and requires the `hooks.json`
+value to be larger — so changing either side without the other fails the suite.
+
+**Reading a human-readable CLI for a control decision cost a silent failure, again.** `apm outdated`
+has no `--json` or other machine-readable flag (confirmed against 0.28.0), so the hook must match
+its prose. The first attempt matched `outdated dependencies found` — plural only. apm emits
+`1 outdated dependency found` in the singular when exactly one package is behind
+(`apm_cli/commands/outdated.py`), so a single stale package was invisible: the hook exited 0
+silently and no refresh ran. With six packages merging independently, one-behind is the ordinary
+case rather than an edge, which means the mechanism failed most often in exactly the situation it
+exists for. The match is now `outdated dependenc(y|ies) found`.
+
+The deeper lesson is the one `post-push` already taught and this repeated: every assertion about the
+hook mocked `apm`, so the suite was green while the hook could not detect the common case. Mocks
+verify the code against its author's belief about the interface, never the interface. The suite now
+carries one probe that stages a genuinely outdated dependency against a local git remote — offline,
+via `url.<path>.insteadOf`, so the twelve-hooks-pass-under-`unshare -rn` property survives — runs
+the real `apm outdated`, and replays its genuine output through the real hook. Reverting the grep
+to plural-only fails it.
 
 **The hook cannot install itself.** Dependencies resolve from the remote, so the hook does not
 deploy until this change is merged and `apm update` has run once against the new default branch.