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:
62
CONTEXT.md
62
CONTEXT.md
@@ -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.
|
||||||
|
|||||||
Reference in New Issue
Block a user