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
This commit is contained in:
2026-08-17 12:28:30 +00:00
parent 36596598ef
commit 4d336bbf35
4 changed files with 61 additions and 12 deletions

View File

@@ -72,6 +72,20 @@ survives those user-scope installs eventually being converted, and the namespace
resolves for anyone installing holocron natively, so skill bodies written for both audiences
should name the bare skill.
**Correction (2026-08-17): the evidence under the correction above is gone, and the claim goes with
it — not to its opposite.** Observed on this machine: `~/.claude/plugins/installed_plugins.json` is
`{"version": 2, "plugins": {}}`; there is no `enabledPlugins` key anywhere in `~/.claude.json`
(`grep -c enabledPlugins` returns 0); `~/.apm/marketplaces.json` is `{"marketplaces": []}`. The
`holocron` entry in `~/.claude/plugins/known_marketplaces.json` survives, but a registered
marketplace is not an installed plugin. So the user-scope installs the 2026-08-14 correction cited
are not there, and neither is the state the *original* consequence described before it. The claim
about the namespaced form has now been written twice off two different observations of the same
machine, and this ADR has already reversed itself once on it. That is the finding: the fact is
machine state, not a property of this decision, and it changes without any commit. No instruction
file — `AGENTS.md`, `CONTEXT.md`, or a skill body — should assert either way whether
`<plugin>:<skill>` resolves. The rule that survives every observation is the one that was always the
actionable half: write the bare name, because it is the only form `apm install` produces.
**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
@@ -117,10 +131,11 @@ pinned `resolved_commit` in `apm.lock.yaml` and does not re-resolve refs (`apm i
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
one still resolves its skills that way. Converting them is a separate decision with a blast radius
beyond this repo.
**User scope is untouched, deliberately.** This decision changed project scope only; whatever is
natively installed at user scope was left alone, and converting it is a separate decision with a
blast radius beyond this repo. The specific inventory this paragraph used to name
(`bin@holocron`, `gitea@holocron`, a stale `hello-world@holocron`) is machine state and is stale —
see the 2026-08-17 correction above. The decision recorded here is unaffected by what that state is.
## Alternatives considered