docs(context): remove unreferenced glossary terms (finding 31)

Corrected scope for audit finding 31: the audit's claim that most of
CONTEXT.md's 28 terms are unused was overstated (13 are must-keep,
referenced in model-facing skill references/*.md files). This cuts only
the 9 confirmed true orphans, independently re-verified by grep across
plugins/*/.apm/, docs/, scripts/, and tests/ with zero hits outside
CONTEXT.md (two had a single incidental ADR mention that doesn't
constitute a dependency): Content mirror, apm-consumed install, Vale
audit prefilter, Vacuous green, Management Application, Sycophancy,
HOTL, Preload tax, Skill context contract.

Term count: 28 -> 19. Also removed two Relationships bullets that
existed solely to relate now-deleted terms (Preload tax/Skill context
contract, and HITL/HOTL/Sycophancy), leaving HITL's own entry to stand
alone. The Preload tax entry's self-contradiction (quoting two dated
character counts immediately after saying not to quote either) is
moot since the whole entry is removed. Example dialogue and flagged
ambiguities sections left untouched per scope, including one now-stale
bold reference to "Preload tax" in flagged ambiguities.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
This commit is contained in:
2026-09-13 21:02:41 +00:00
parent 1b01e25f3b
commit 124ce6eaa9

View File

@@ -14,22 +14,6 @@ decisions.
### Context cost ### Context cost
**Preload tax**:
The always-on context cost of every installed skill's `name` and `description`, charged from the
first token of every session whether the skill is invoked or not. Measurement method: ADR-0020. Its
**23,427 characters is the pre-retrofit baseline, not a current reading** — measured at the decision
commit, before #99. Across the same 39 skills it is **10,478 characters** (~2,620 tokens) as of
2026-09-01. Both figures move with the corpus, so re-derive rather than quote either: sum
`len(name) + len(description)` over the frontmatter of every `plugins/*/.apm/skills/*/SKILL.md`,
folding block scalars as `scripts/skill-size-check.sh` does.
_Avoid_: context cost, token overhead
**Skill context contract**:
The ADR-0020 authoring rules that hold the preload tax and body size down — a description carries a
trigger clause, at most one capability clause, and a boundary clause, and nothing else. Thresholds
and the target-resolution walk: `docs/spec/gates.md`.
_Avoid_: skill budget, size limit
**Routing target**: **Routing target**:
The skill or agent name a boundary clause sends work to. It **resolves** when a skill or agent of The skill or agent name a boundary clause sends work to. It **resolves** when a skill or agent of
that name is reachable from the file being checked, and **dangles** when none is — a route the router that name is reachable from the file being checked, and **dangles** when none is — a route the router
@@ -76,12 +60,6 @@ The unit apm builds and installs — `plugins/<name>/apm.yml` plus the hand-auth
`plugins/<name>/.apm/` tree it compiles from (ADR-0015). `plugins/<name>/.apm/` tree it compiles from (ADR-0015).
_Avoid_: plugin directory, source tree _Avoid_: plugin directory, source tree
**Content mirror**:
The generated flat `skills/`, `agents/`, `commands/`, `instructions/`, `extensions/` directories and
merged `hooks/hooks.json` at a plugin root — also called the flat mirror — compiled from that
plugin's `.apm/` tree so hosts that convention-scan those paths discover the content (ADR-0017).
_Avoid_: generated copy, duplicate tree
**Output profile**: **Output profile**:
An `apm pack` target format for a generated *marketplace* manifest; apm has `claude` An `apm pack` target format for a generated *marketplace* manifest; apm has `claude`
(`.claude-plugin/marketplace.json`) and `codex` (the differently-shaped (`.claude-plugin/marketplace.json`) and `codex` (the differently-shaped
@@ -99,12 +77,6 @@ This repository, in its role as a plugin marketplace and as the remote the six p
resolve against. resolve against.
_Avoid_: the marketplace, upstream _Avoid_: the marketplace, upstream
**apm-consumed install**:
How this repo installs its own plugins as of 2026-08-14 — six `dependencies.apm` entries in the root
`apm.yml` deployed by `apm install`, rather than `claude plugin install <name>@holocron`. Its
consequences: ADR-0018.
_Avoid_: apm install, dependency install
**Provenance chain**: **Provenance chain**:
The three-stage traceability record linking a skill back to its research inputs: `/research` produces The three-stage traceability record linking a skill back to its research inputs: `/research` produces
topic docs and a `sources.md`; the author skill records which sources informed which files in topic docs and a `sources.md`; the author skill records which sources informed which files in
@@ -120,18 +92,6 @@ irreversible or high-stakes actions — architecture changes, production deploym
configuration. configuration.
_Avoid_: manual approval, gated action _Avoid_: manual approval, gated action
**HOTL** (human-on-the-loop):
The agent acts and a human monitors, able to intervene after the fact. Acceptable only for
low-stakes, bounded, reversible actions where the cost of pausing exceeds the blast radius of an
error.
_Avoid_: autonomous, unsupervised
**Sycophancy**:
The failure mode where an RLHF-trained model prioritises approval over accuracy — changing a correct
answer to a wrong one under user pressure, then persisting in the wrong answer. Treated here as a
first-class reliability risk, not a quality-of-life concern.
_Avoid_: agreeableness, people-pleasing
### Documents ### Documents
**AGENTS.md**: **AGENTS.md**:
@@ -149,12 +109,6 @@ _Avoid_: wrapper, shim, provider file
The long-loop feedback log for patterns observed across sessions, at the repo root. The long-loop feedback log for patterns observed across sessions, at the repo root.
_Avoid_: changelog, retro, postmortem _Avoid_: changelog, retro, postmortem
**Management Application**:
A separate product in a separate repo for browsing, editing, and configuring AI development configs
through a product UI, with Git as an invisible persistence layer. Repo-agnostic; this repo is its
canonical default content. Roadmap: `docs/VISION.md`.
_Avoid_: the UI, the dashboard, the app
### Quality ### Quality
**Skill composition**: **Skill composition**:
@@ -162,11 +116,6 @@ A skill calling another skill by name to delegate a sub-task — the caller owns
decision ("when to do X"), the callee owns the mechanics ("how to do X"). decision ("when to do X"), the callee owns the mechanics ("how to do X").
_Avoid_: chaining, nesting, sub-skill _Avoid_: chaining, nesting, sub-skill
**Vale audit prefilter**:
The deterministic Vale pass that runs ahead of `skill-audit`/`agent-audit`'s Description dimension,
so LLM judgment is spent only on what a pattern cannot catch. Mechanics: `docs/spec/gates.md`.
_Avoid_: linting, style check
**Authoring root**: **Authoring root**:
The directory a gate resolves against — the nearest ancestor of the file being checked holding The directory a gate resolves against — the nearest ancestor of the file being checked holding
`plugins/*/.apm/skills` or `plugins/*/.apm/agents`, falling back to the nearest ancestor holding `plugins/*/.apm/skills` or `plugins/*/.apm/agents`, falling back to the nearest ancestor holding
@@ -179,11 +128,6 @@ sibling that would wrongly answer it; boundary clauses exist to exclude genuine
than to enumerate siblings. Detail: `skill-audit/references/description-quality.md`. than to enumerate siblings. Detail: `skill-audit/references/description-quality.md`.
_Avoid_: overlap, similar skill _Avoid_: overlap, similar skill
**Vacuous green**:
A check that reports success because it measured nothing — zero files scanned, an unparsed value read
as empty, a conditional branch that never armed.
_Avoid_: false pass, clean run
**Issue**: **Issue**:
The cross-provider term for a tracked unit of work. Gitea is this repo's canonical tracker The cross-provider term for a tracked unit of work. Gitea is this repo's canonical tracker
(ADR-0007), but skills say "linked issue" generically rather than naming a provider. (ADR-0007), but skills say "linked issue" generically rather than naming a provider.
@@ -193,18 +137,12 @@ _Avoid_: ticket, card, task
- A **Plugin** bundles one or more **Skills** and agents; a **Plugin marketplace** lists **Plugins**; - A **Plugin** bundles one or more **Skills** and agents; a **Plugin marketplace** lists **Plugins**;
**holocron** is this repo wearing that hat. **holocron** is this repo wearing that hat.
- Every model-invocable **Skill** pays the **Preload tax**. A **Hand-invoked skill** does not — which
is the first question to settle when authoring one.
- The **Skill context contract** bounds both the **Preload tax** (description) and the body.
A **Dispatch body** is how a skill stays inside it; **Delegation discipline** is how an agent does.
- **AGENTS.md** is the source of always-on rules; a **Thin adapter** imports it and originates - **AGENTS.md** is the source of always-on rules; a **Thin adapter** imports it and originates
nothing. nothing.
- **Skill composition** is the caller/callee split. `forge` routes a genuinely *undecided* artifact - **Skill composition** is the caller/callee split. `forge` routes a genuinely *undecided* artifact
type to the matching author skill — an already-specified fix (file, line, and change known) calls type to the matching author skill — an already-specified fix (file, line, and change known) calls
that author skill directly, because each routing hop re-derives instructions from a shorter brief that author skill directly, because each routing hop re-derives instructions from a shorter brief
and has been observed to drop hard constraints handed down the chain. and has been observed to drop hard constraints handed down the chain.
- **HITL** and **HOTL** are exclusive per action class, and the choice must be explicit and
documented. **Sycophancy** is why HOTL is not the safe default.
- A **Skill** built on research carries a **Provenance chain**; `skill-audit` fails it when broken. - A **Skill** built on research carries a **Provenance chain**; `skill-audit` fails it when broken.
- **LESSONS.md** feeds the standing files: three or more entries on one pattern graduate the pattern - **LESSONS.md** feeds the standing files: three or more entries on one pattern graduate the pattern
into the relevant standing document. into the relevant standing document.