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

docs: cut the every-session context set by 74%, and fix what the cut broke #105

Merged
Defame1297 merged 16 commits from docs/slim-agents-md into main 2026-08-17 14:08:24 +00:00
Conversation 2 Commits 16 Files Changed 32 +1694 -261
Claude commented 2026-08-17 10:32:03 +00:00
Collaborator
Copy Link

Trims the two files every session pays for, then fixes the fifteen defects a full review of that trim found.

Why

AGENTS.md is preloaded via CLAUDE.md's @AGENTS.md import, and AGENTS.md in turn instructs reading CONTEXT.md and docs/VISION.md. Every word in that set is a tax paid whether or not it is relevant to the session.

File Before After
AGENTS.md (preloaded) 24,219 B 6,808 B −72%
CONTEXT.md (instructed read) 33,799 B 9,762 B −71%
docs/VISION.md (instructed read) 4,671 B — demoted to on-demand
Total ~15,700 tok ~4,140 tok −74%

Nothing was deleted that wasn't either relocated or independently verified as already carried elsewhere.

What moved where

Content was split by audience rather than by heading:

  • One-time setup, prerequisites, test commands → a new root README.md, which did not previously exist.
  • Gate forensics — why a hook is shaped as it is, what was tried and rejected, verification numbers → a new docs/spec/gates.md. Every constant, hook ID, error string and tried-and-rejected note was preserved; these exist to stop settled decisions being re-litigated.
  • The Vale prefilter mechanics (a 1,444-word CONTEXT.md glossary entry) → nine subsections of gates.md.
  • Instruction-file format, the bidirectional-reference principle, plugin scope → docs/spec/architecture.md. The reference principle is flagged aspirational: no instruction file carries a when: field, only 2 of 39 skills do, and the scanner script it names does not exist.
  • CONTEXT.md was restructured to conform to grill-with-docs's own CONTEXT-FORMAT.md template, which it had never followed — 23 glossary entries averaging 190 words against a documented "one sentence max".

Review findings, and the fixes

A four-way review (content-loss audit on each trimmed file, a dangling-reference sweep, and a fact-check of the new prose against the repo) found 15 defects. All are fixed in commits 4–9.

Content loss: two real drops, both restored. The apm pack-won't-refresh-the-mirror warning and the plugin self-containment constraint. Both were guard-rails that fired from preloaded context, so restoring the sentence to an on-demand doc would have restored the text without the function. They are placed by when they need to fire: the first now lives in the DRIFT failure message of the hook that already catches that exact mistake; the second in architecture.md beside the mechanism, since no gate catches it.

Dangling references: 11 across 8 files. Six were rationale comments in scripts/ and tests/ citing CONTEXT.md text that moved. These were re-anchored to ADR-0013 where it owns the fact, and had their citation dropped entirely where no ADR does — the quote was already inline, so the citation added a rot surface and no information. Two ADRs (0007, 0015) that the trim missed now carry dated amendments, matching the three that got them.

Stale claims. CONTEXT.md pointed at gates.md for a measurement method that lives in ADR-0020, and carried a token figure that was wrong three days after being written — dropped rather than re-measured, since it was the file's only live number. It also named a session-handoff skill that does not exist.

Published metadata was wrong. gitea's marketplace description advertised wikis (no wiki skill exists) while omitting gitea-branches and gitea-files; git's advertised pull requests, which are gitea's, while omitting pc-author/pc-run. This is the same defect bb9158d fixed on core in August, so the fix follows that precedent — package apm.yml and root marketplace entry together, versions bumped, manifests regenerated.

To stop it recurring a third time, the two sources now have distinct jobs: published descriptions enumerate (a consumer needs to know what they get), architecture.md's table states routing boundaries only (it answers "where does a new skill go"). They are supposed to differ, so nobody should be diffing them.

Versions

git 1.3.3 → 1.3.4, gitea 1.3.4 → 1.3.5, marketplace 0.4.2 → 0.4.3 — all PATCH for metadata under the per_package strategy.

A release tag is likely needed at merge. check-release-needed only fires against refs/heads/main, so it stayed silent on the feature-branch pushes, but the version bumps above are exactly what it exists to catch.

Verification

  • pre-commit run --hook-stage pre-push --all-files — 16/16 Passed, exit 0
  • bash tests/run-tests.sh — full suite green
  • agentsmd-audit — secrets clean, drift clean, informational findings only for sections deliberately relocated to the README
  • Clean fast-forward onto main; no commits on main since the branch point
  • Regenerated marketplace diff is exactly ten lines, no incidental churn

Known trade, not a defect

AGENTS.md now says "14 repo-defined hooks" while the command it hands you prints 16; the reconciliation (pre-commit's two meta hooks declare no stages:) moved to gates.md. Same shape for the pretty-format-json guard. Both previously fired from preloaded context and now require opening gates.md first. That is the deliberate cost of the trim, recorded here rather than left to be rediscovered.

Refs: #99

Trims the two files every session pays for, then fixes the fifteen defects a full review of that trim found. ## Why `AGENTS.md` is preloaded via `CLAUDE.md`'s `@AGENTS.md` import, and `AGENTS.md` in turn instructs reading `CONTEXT.md` and `docs/VISION.md`. Every word in that set is a tax paid whether or not it is relevant to the session. | File | Before | After | | |---|---:|---:|---| | `AGENTS.md` (preloaded) | 24,219 B | 6,808 B | −72% | | `CONTEXT.md` (instructed read) | 33,799 B | 9,762 B | −71% | | `docs/VISION.md` (instructed read) | 4,671 B | — | demoted to on-demand | | **Total** | **~15,700 tok** | **~4,140 tok** | **−74%** | Nothing was deleted that wasn't either relocated or independently verified as already carried elsewhere. ## What moved where Content was split by audience rather than by heading: - **One-time setup, prerequisites, test commands** → a new root `README.md`, which did not previously exist. - **Gate forensics** — why a hook is shaped as it is, what was tried and rejected, verification numbers → a new `docs/spec/gates.md`. Every constant, hook ID, error string and tried-and-rejected note was preserved; these exist to stop settled decisions being re-litigated. - **The Vale prefilter mechanics** (a 1,444-word `CONTEXT.md` glossary entry) → nine subsections of `gates.md`. - **Instruction-file format, the bidirectional-reference principle, plugin scope** → `docs/spec/architecture.md`. The reference principle is flagged aspirational: no instruction file carries a `when:` field, only 2 of 39 skills do, and the scanner script it names does not exist. - **`CONTEXT.md`** was restructured to conform to `grill-with-docs`'s own `CONTEXT-FORMAT.md` template, which it had never followed — 23 glossary entries averaging 190 words against a documented "one sentence max". ## Review findings, and the fixes A four-way review (content-loss audit on each trimmed file, a dangling-reference sweep, and a fact-check of the new prose against the repo) found 15 defects. All are fixed in commits 4–9. **Content loss: two real drops, both restored.** The `apm pack`-won't-refresh-the-mirror warning and the plugin self-containment constraint. Both were guard-rails that fired from preloaded context, so restoring the sentence to an on-demand doc would have restored the text without the function. They are placed by *when they need to fire*: the first now lives in the DRIFT failure message of the hook that already catches that exact mistake; the second in `architecture.md` beside the mechanism, since no gate catches it. **Dangling references: 11 across 8 files.** Six were rationale comments in `scripts/` and `tests/` citing `CONTEXT.md` text that moved. These were re-anchored to **ADR-0013** where it owns the fact, and had their citation dropped entirely where no ADR does — the quote was already inline, so the citation added a rot surface and no information. Two ADRs (0007, 0015) that the trim missed now carry dated amendments, matching the three that got them. **Stale claims.** `CONTEXT.md` pointed at `gates.md` for a measurement method that lives in ADR-0020, and carried a token figure that was wrong three days after being written — dropped rather than re-measured, since it was the file's only live number. It also named a `session-handoff` skill that does not exist. **Published metadata was wrong.** `gitea`'s marketplace description advertised wikis (no wiki skill exists) while omitting `gitea-branches` and `gitea-files`; `git`'s advertised pull requests, which are gitea's, while omitting `pc-author`/`pc-run`. This is the same defect `bb9158d` fixed on `core` in August, so the fix follows that precedent — package `apm.yml` and root marketplace entry together, versions bumped, manifests regenerated. To stop it recurring a third time, the two sources now have distinct jobs: **published descriptions enumerate** (a consumer needs to know what they get), **`architecture.md`'s table states routing boundaries only** (it answers "where does a new skill go"). They are supposed to differ, so nobody should be diffing them. ## Versions `git` 1.3.3 → 1.3.4, `gitea` 1.3.4 → 1.3.5, marketplace 0.4.2 → 0.4.3 — all PATCH for metadata under the `per_package` strategy. **A release tag is likely needed at merge.** `check-release-needed` only fires against `refs/heads/main`, so it stayed silent on the feature-branch pushes, but the version bumps above are exactly what it exists to catch. ## Verification - `pre-commit run --hook-stage pre-push --all-files` — 16/16 Passed, exit 0 - `bash tests/run-tests.sh` — full suite green - `agentsmd-audit` — secrets clean, drift clean, informational findings only for sections deliberately relocated to the README - Clean fast-forward onto `main`; no commits on `main` since the branch point - Regenerated marketplace diff is exactly ten lines, no incidental churn ## Known trade, not a defect `AGENTS.md` now says "14 repo-defined hooks" while the command it hands you prints **16**; the reconciliation (pre-commit's two `meta` hooks declare no `stages:`) moved to `gates.md`. Same shape for the `pretty-format-json` guard. Both previously fired from preloaded context and now require opening `gates.md` first. That is the deliberate cost of the trim, recorded here rather than left to be rediscovered. Refs: #99
Claude added 9 commits 2026-08-17 10:32:03 +00:00
chore(apm): refresh lock after SessionStart auto-update 123ece2fb3 
Why: kyberforge's SessionStart hook found six packages behind the holocron
default branch and ran `apm update --yes`, which re-resolved every unpinned
dependency ref and rewrote the lock. The dependencies are declared unpinned
against the default branch, so this churn is expected rather than a defect.

Impact: pins the deployed skill and agent set to the refs resolved this
session. No manifest or plugin content changed.
docs: slim AGENTS.md to per-session context only 1929ffd2da 
Why: AGENTS.md is preloaded into every session via CLAUDE.md's @AGENTS.md
import, so every word is a tax paid whether or not it is relevant. It had
grown to 3,371 words (~4,550 tokens), 75% of it a single "Setup and testing"
section that was mostly neither: roughly 1,600 words were gate forensics —
why a hook is shaped the way it is, what was tried and rejected, verification
numbers — and only ~390 words were genuine one-time setup.

Implementation notes: split three ways by audience rather than by heading.
One-time setup, prerequisites and test commands move to a new root README.md,
which did not previously exist. The gate forensics move to a new
docs/spec/gates.md, preserving every constant, hook ID, error string and
tried-and-rejected note (policy.fetch_failure_default, the removed fallback
frontmatter reader, extending skill-size-check's files: pattern to agents,
tidying .claude/settings.json out of the pretty-format-json exclude list) —
these exist to stop settled decisions being re-litigated, so none were
dropped. AGENTS.md keeps only what applies every session, at one clause of
rationale per rule. The .apm/-mirror section collapses to a pointer because
docs/spec/architecture.md already covers it in full. The hot ADR-0020 gate
counts stay in AGENTS.md deliberately: they block any skill edit today.

Also corrects docs/spec/architecture.md's stale claim of 19 ADRs; ADR-0020
landed without updating the count.

Impact: per-session preload drops from ~4,550 to ~1,116 tokens, a 75% cut.
agentsmd-audit passes: secrets clean, drift clean, 4 informational findings
for sections deliberately relocated to the README.
docs: trim CONTEXT.md to a glossary and demote VISION.md b9c7762463 
Why: CONTEXT.md is an instructed every-session read at 33,799 bytes (~8,450
tokens), and CONTEXT.md:17 layered docs/VISION.md on top. After the AGENTS.md
trim, that left ~9,650 tokens of instructed reads sitting behind a file whose
own format contract — grill-with-docs/CONTEXT-FORMAT.md:43, "Keep definitions
tight. One sentence max." — it was not following. 22 glossary entries averaged
190 words; the top four were 55% of the file, and one ("Vale audit prefilter")
was 1,444 words of pre-commit forensics filed as a definition.

Implementation notes:
- CONTEXT.md rewritten to CONTEXT-FORMAT.md's prescribed template: ## Language
  (five clusters, 22 terms with _Avoid_ aliases), ## Relationships,
  ## Example dialogue, ## Flagged ambiguities. 33,799 -> 9,762 bytes.
- Vale prefilter forensics moved to docs/spec/gates.md under nine subsections:
  the two-copy style layout, vale-wrap.sh and the Vale 3.15.2
  text.frontmatter.description limitation, the --config argv defect (E100),
  glob scoping, the rule inventory, and 0-files-means-NOT-RUN.
- Instruction-file format and the bidirectional-reference principle moved to
  docs/spec/architecture.md, the latter flagged as aspirational: no instruction
  file carries a `when:` field, only 2 of 39 skills do, and the reference
  scanner script it names does not exist.
- Added a per-plugin scope table to architecture.md so "which plugin owns this
  skill" survives the trim, and corrected its claim that the content index
  lives in providers/claude-code/CLAUDE.md — that file is now two import lines
  and the index sits in core/AGENTS.md.
- "Repo and Gitea are the only source of truth" moved from CONTEXT.md's
  Principles into AGENTS.md session rules; it was operative guidance in a
  glossary. docs/VISION.md and LESSONS.md added to the on-demand list.
- The apm-consumed install entry (432 words) was deleted outright: all four
  consequences are already carried by README.md, ADR-0018, gates.md and
  AGENTS.md.
- ADR-0013, ADR-0015 and ADR-0017 each pointed at CONTEXT.md sections that
  moved; amended with dated supersession notes rather than left dangling.

Impact: the every-session set drops from ~15,700 to ~4,140 tokens across both
passes (-74%). The deleted "lint plugin" entry was also stale on a safety
claim — it said lint-runner inherits Edit, but ADR-0016 restored
`disallowedTools: Edit, Write, NotebookEdit` and CONTEXT.md was never updated.

Refs: #99
docs: fix a wrong pointer and two stale claims in CONTEXT.md b93af30750 
Why: CONTEXT.md is an instructed every-session read, so a wrong assertion in it
is cited downstream without being checked. The b9c7762 rewrite introduced one
broken pointer and carried over two claims that were already false.

Implementation notes:
- The Preload tax entry pointed at docs/spec/gates.md for the measurement
  method. gates.md has no such method — it uses the 23,427-char figure once, in
  passing, without deriving it. The method and the current figure both live in
  ADR-0020, which is where a dated measurement belongs: it is superseded there
  deliberately, and issue #99 tracks its drift.
- Dropped the "~5,900 tokens across 39 skills" measurement rather than
  re-measuring it. It was already wrong three days after being written (~5,340
  today) and it was the only live number in the file. Every sibling entry is one
  definitional sentence plus a pointer fragment; this one now matches, and
  CONTEXT-FORMAT.md:43 asks for exactly that.
- Dropped "Written by the session-handoff skill or directly by the human" from
  the LESSONS.md entry. No session-handoff skill exists — LESSONS.md:7 records
  it as planned work. Who writes a file is not its definition.

Impact: removes the only rot surface in the file and the only assertion in it
that names an artifact the repo does not have.

Refs: #99
fix: re-anchor doc citations that the CONTEXT.md trim broke 56cc173f65 
Why: eight comments and one status note cited CONTEXT.md or AGENTS.md text that
b9c7762 and 1929ffd moved or deleted. All are inert at runtime, but they are the
rationale comments that tell the next maintainer why an assertion exists, and
they now name a file that no longer explains it.

Implementation notes: re-anchored by what the citation is for, not uniformly.
- Four sites quoted facts ADR-0013 owns — every rule is `level: error` with no
  ignorable tier (ADR-0013:59-70), and KyberforgeCopilot's `.agent.md`-only
  scope (ADR-0013:43-46). These now cite ADR-0013. ADRs are append-only here;
  the spec docs are refactored, which is what caused this rot.
- Two sites quoted the glob location-independence property, which no ADR owns.
  The quote was already inline and carried the full rationale, so the citation
  added a rot surface and no information — dropped, statement kept.
- sync-marketplace-mirror.sh's header attributed the mirror-not-a-profile fact
  to CONTEXT.md; the parenthetical beside it already carries the evidence, so
  the attribution is dropped rather than re-pointed.
- .pre-commit-config.yaml cited an AGENTS.md instruction that no longer exists;
  generalised to "the documented instruction".
- LESSONS.md:29 misquoted AGENTS.md's current session-start line.

Also corrects a pre-existing misattribution at tests/test-vale-wrap.sh:454:
AGENTS.md has never named bash 3.2 as a repo target (`git log -S'3.2'` on it is
empty). LESSONS.md and the script headers do.

Impact: no behaviour change. test-check-vale-style-sync.sh and test-vale-wrap.sh
both pass (42 passed, 0 failed).
docs(adr): amend ADR-0007 and ADR-0015 for the CONTEXT.md trim ba7cec7672 
Why: b9c7762 gave dated amendments to ADR-0013, ADR-0015 and ADR-0017, but two
pointers were missed. ADR-0007 cited the "Provider-agnostic issue tracker"
glossary entry, which the trim renamed to "Issue". ADR-0015 cited the "lint
plugin" entry, which the trim deleted outright — and ADR-0015 was amended for
its other CONTEXT.md pointer in the same commit, so this one was missed inside
an already-edited file.

Implementation notes: ADR-0007 gets a dated parenthetical matching the pattern
the other three carry, confirming the entry survived under a new name rather
than being dropped. ADR-0015's Considered-options parenthetical is re-pointed
at docs/spec/architecture.md's plugin scope table, which now carries the
repo-agnostic-versus-marketplace-specific argument the deleted entry held, and
its existing 2026-08-17 supersession note is extended to record that second
redirect in one place.

Impact: all four ADRs that referenced moved CONTEXT.md content now say where the
content went. No decision is altered.
docs: restore two guard-rails the trim dropped bd2bf667c5 
Why: 1929ffd and b9c7762 preserved every constant, hook ID and error string,
but two don't-re-litigate notes were lost. Both were guard-rails — they fired
from preloaded context, before the mistake. Restoring the sentence to an
on-demand spec doc restores the text without restoring the function, since an
on-demand file is opened after a plan is formed, not before.

Implementation notes: placed by when each note must fire, not by what it is
about.
- "Do not expect `apm pack` to refresh the .github/plugin/marketplace.json
  mirror" now lives in the DRIFT failure message of the script and hook that
  already catch that exact mistake. It costs no preloaded tokens, fires at the
  moment of the error, and cannot be missed. No test asserts on that message;
  --check and shellcheck both pass.
- Plugin self-containment has no gate that fires on it, so it goes in
  architecture.md's Plugin model beside "self-contained plugin units", stated as
  the constraint it is rather than a description, with the two consequences that
  make it load-bearing: the duplicated Vale styles (ADR-0014) and ADR-0020's
  constants copied into three validators.

Impact: the every-session set is unchanged — neither note returns to AGENTS.md.
docs: correct plugin scope, hook ordering and the setup gap b0ef503485 
Why: the review found architecture.md's plugin table and README's plugin list
were both written by enumerating what happened to be in each plugin, so both
went stale immediately — README credited `git` with pull requests it has no
skill for, and both omitted `pc-author`/`pc-run`. bb9158d fixed this same class
on `core` in August and it recurred here, so the fix is to stop enumerating in
the place whose job is routing.

Implementation notes:
- architecture.md's table now states routing boundaries only, with a note saying
  so and pointing at each plugin's published apm.yml description for the actual
  inventory. Two boundaries are named explicitly: `core` vs `kyberforge` (kept),
  and `git` vs `gitea` — wire protocol against a local clone versus the forge's
  HTTP API, which is why git-branches and gitea-branches are not duplicates.
- The `git` row is widened to cover git hook tooling rather than moving
  pc-author/pc-run elsewhere. pre-commit manages .git/hooks/, so the placement
  was always right and the row was simply under-described.
- README's setup block had a comment where step 2's command should be. It now
  carries `pre-commit install -t pre-commit -t commit-msg -t pre-push`, verified
  against the three stages in .pre-commit-config.yaml and the three hooks in
  .git/hooks/. pc-run is still named, as the option rather than the only path.
- README:11 said each plugin carries agents, hooks and MCP servers. Only
  kyberforge ships hooks and only bin ships an MCP server.
- gates.md:30 claimed its hook list was in config order; it is grouped by
  concern, which is the better layout, so the claim is corrected to match.

Impact: docs-only. gitea's published description is corrected separately, since
that regenerates consumer-facing manifests.
chore(apm): correct git and gitea published descriptions and regenerate 65bac15257 
Why: both plugins' published descriptions named capabilities that do not exist
and omitted ones that do. `gitea` advertised wikis — no wiki skill exists and
`grep -ri wiki plugins/gitea/.apm/` is empty — while omitting gitea-branches and
gitea-files. `git` advertised pull requests, which are gitea's, while omitting
pc-author/pc-run, git-submodules and git-workflow. These are compiled into
plugin.json and both marketplace.json files, so they are published metadata, not
internal notes.

This is the same defect bb9158d fixed on `core` in August, so the fix follows
that precedent exactly: correct the package apm.yml and the root marketplace
entry together — fixing only the package manifest leaves it half-propagated,
since the root entry is what reaches the compiled marketplace.

Implementation notes:
- git 1.3.3 -> 1.3.4, gitea 1.3.4 -> 1.3.5, marketplace 0.4.2 -> 0.4.3, all
  PATCH for metadata under the per_package strategy at apm.yml:76.
- Regenerated with `apm pack` for the two marketplace manifests and
  `scripts/sync-plugin-content.sh --all` for the four per-plugin plugin.json
  files; `apm pack` alone does not touch those. `scripts/sync-marketplace-mirror.sh`
  refreshed the Copilot legacy mirror, which no apm profile targets.
- README's gitea line mirrors the new published description. The routing
  boundaries in architecture.md deliberately do not, since they answer a
  different question.

Impact: consumer-facing. Anyone reading the marketplace now sees what these
plugins ship. apm-pack-check-clean, check-plugin-content-sync,
check-marketplace-mirror-sync, validate-marketplace and apm-audit-ci all pass.
Defame1297 added 1 commit 2026-08-17 10:38:54 +00:00
chore(apm): give bin a published description that describes it de84d1b677 
Why: bin's marketplace description read "A place for things to be binned" — a
routing boundary sitting in the enumeration slot, phrased as a joke. It is what
a consumer sees in the marketplace listing for a plugin shipping eleven
substantive skills: research, write-docs, tdd, prototype, triage, diagnose,
improve-codebase-architecture, grill-me, grill-with-docs, zoom-out and caveman.

This is the same category error b0ef503 fixed for git and gitea, and the same
text bb9158d moved out of core's description in August — "triage, diagnosis,
architecture review" left core precisely because those skills live in bin, so
bin is where it should have landed.

Implementation notes: bin 1.1.3 -> 1.1.4, marketplace 0.4.3 -> 0.4.4, PATCH for
metadata under the per_package strategy. README's bin line mirrors the new
description. architecture.md's routing boundary is deliberately left as
"unsorted skills that have not earned a home yet" — that is still true, and it
answers a different question than the listing does.

Impact: consumer-facing. apm-pack-check-clean, check-plugin-content-sync,
check-marketplace-mirror-sync, validate-marketplace, validate-plugins and
apm-audit-ci all pass.
Defame1297 added 6 commits 2026-08-17 13:30:05 +00:00
fix(scripts): make the mirror DRIFT fix line safe to copy-paste b1ea14df3e 
Why: bd2bf66 restored the `apm pack` guard-rail by appending it to the `Fix:`
command after `--`, which made the printed line stop being runnable. Pasting it
ran the script with ~24 stray argv entries: `${1:-}` became `--`, so CHECK
stayed 0, no shift occurred, and `[[ $# -eq 0 ]] || usage` printed usage and
exited 1. The user got a usage error from the tool meant to fix their problem,
and the mirror stayed stale.

The unquoted backticks around `apm pack` were a second hazard in the same line:
the paste command-substituted a real `apm pack` run before this script was ever
reached, so the first error a user saw came from apm, not from here.

Implementation notes:
- The runnable command now stands alone on its own line, and the rationale
  follows as a separate `Note:` echo.
- Backticks downgraded to single quotes; a line printed next to a
  copy-pasteable command must not contain shell metacharacters.
- The guard-rail text is otherwise preserved verbatim. It exists because apm
  ships no output profile targeting this path, so `apm pack` does not refresh
  it, and expecting it to is the drift this hook prevents.

Impact: reproduced the break on a scratch copy, then verified the fix by pasting
the printed command verbatim — exit 0, mirror synced, re-check clean.
tests/test-sync-marketplace-mirror.sh asserts only exit codes and file contents,
so nothing pins this message and it could regress silently; tracked separately.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
fix(tests): point the strict-mode dependency citation at README.md 36596598ef 
Why: this branch moved the prerequisites list out of AGENTS.md into README.md
but left three references behind. The worst is run-tests.sh's --strict failure
message, which a developer is handed at the exact moment a push gate fails and
they need the dependency list: it named AGENTS.md, which no longer documents
vale, apm or jq anywhere. 56cc173 re-anchored this same class of citation in
.pre-commit-config.yaml, scripts/check-vale-style-sync.sh,
scripts/sync-marketplace-mirror.sh and tests/test-check-vale-style-sync.sh --
tests/run-tests.sh was missed, and it is the only one a human actually reads.

Implementation notes:
- run-tests.sh:262 (user-visible), run-tests.sh:16 (header rationale) and
  test-run-tests.sh:395 all now cite README.md's Prerequisites table, verified
  to name vale, apm, jq, python3/PyYAML and the claude CLI.
- Every assertion on this message greps for "a skip is a SETUP ERROR", which
  sits before the changed clause, so no test needed updating.
- test-vale-wrap.sh's bash 3.2 citation is corrected in the same pass: it
  credited LESSONS.md and the script headers, but LESSONS.md's only mention of
  3.2 is an aside inside an unrelated lesson, not a target declaration. It now
  cites scripts/lib/batch-run.sh and providers/claude-code/statusline-command.sh,
  which do declare it. The citation 56cc173 replaced was already false, so this
  finishes a half-fix rather than correcting a regression.

Impact: forced the strict-failure path with vale removed from PATH and confirmed
the corrected message printing -- 21 passed, 3 skipped, exit 1. Full suite with
vale present: 24 passed, 0 skipped, 0 failed.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
docs: stop the preloaded instruction set asserting machine state 4d336bbf35 
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
chore(apm): retire skill enumeration from published descriptions c7ba3d2ccf 
Why: enumerating a plugin's skills in its published description has now failed
three times in four days, the third time inside the correction for the second.

bb9158d (Aug 14) fixed core's description, which described bin's skills. That
failure was wrong content, not an incomplete list -- a syntactically perfect
four-item enumeration that belonged to a different plugin -- so enumerating
harder could not have caught it, and bb9158d's own fix replaced the enumeration
with a domain boundary. 65bac15 and de84d1b then cited that precedent while
doing the opposite, and the re-enumeration is itself incomplete: caveman and
zoom-out are unnamed in bin, git-workflow is unnamed in git despite 65bac15's
message claiming it was added, and gitea-workflow is unnamed in gitea. 23 of 27
skills named at the third attempt.

Nothing checks any of this. check-manifests.sh does not contain the string
"description"; apm audit --ci, apm pack --check-clean and
sync-plugin-content.sh --check all compare compiled output against apm.yml, so
their job is to propagate whatever it says byte-for-byte. The wiki claim passed
all fourteen pre-push hooks every day it was published. Enumeration also makes a
marketplace release the consequence of a directory appearing.

Implementation notes:
- ADR-0021 records the decision, the three failures, and why no gate is added:
  the check is one-directional, cannot see an invented capability, and a
  correspondence map would relocate the same per-skill maintenance one file over.
- bin 1.1.4 -> 1.1.5, git 1.3.4 -> 1.3.5, gitea 1.3.5 -> 1.3.6,
  marketplace.version 0.4.4 -> 0.4.5, all PATCH under per_package.
- apm.yml's top-level version: is restored to lockstep at 0.4.5. It has moved
  with marketplace.version in all eleven commits that ever touched the file
  until this branch left it at 0.4.2, and apm.yml's own comment records it as
  live and consumed by apm audit.
- git's boundary names the pre-commit hooks explicitly: pc-author and pc-run are
  not git operations, and a boundary drawn narrower than the contents is the
  same defect one level up.
- Regenerated with apm pack for the marketplace manifests and
  sync-plugin-content.sh --all for the per-plugin ones; both mirrors verified
  byte-identical.

Impact: consumer-facing. 16/16 pre-push hooks pass, suite green, generated diff
is 26 insertions and 26 deletions across 8 files with no incidental churn.

Refs: #105
ADR: 0021

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
docs(spec): correct eight claims the trim carried into the new files c68e864159 
Why: the relocation into gates.md and architecture.md moved text faster than it
verified it, and a review found eight assertions that do not survive contact
with the repo.

- gates.md cited docs/research/examples/, which does not exist; the tree is at
  plugins/kyberforge/docs/research/examples/. The same wrong string survives at
  ADR-0013:98, where it originated, and is tracked separately.
- gates.md's description-budget arithmetic was built on 23,427, a figure
  ADR-0020 measured at f9b919d and pins there, and compared a name-inclusive
  total against a description-only ceiling. Dropped rather than re-measured,
  following the precedent this branch set for CONTEXT.md's token figure: a
  second live copy is a second thing to go stale.
- gates.md listed "every boundary-clause routing target must resolve" as a hard
  FAIL. skill-size-check.sh emits unresolved targets as SUGGESTION by default,
  promotes to ERROR only when terminal and either route-notated or corroborated
  by a resolving target in the same sentence, and reports INFO DID NOT RUN when
  no universe resolves. Verified with five fixtures; replaced with a
  three-verdict table.
- gates.md and README called `pre-commit run --hook-stage pre-push --all-files`
  the whole push gate. check-release-needed.sh exits 0 unless
  PRE_COMMIT_REMOTE_BRANCH is refs/heads/main, which only the real git hook
  exports -- its own header comment titles this a "Known gap".
- "repo-defined" was loose: the two meta hooks are also declared here, and what
  separates them is repo: meta from repo: local.
- architecture.md claimed `when:` appears in two of 39 skill sources. Exactly
  one SKILL.md carries it; the second hit is a META.md. The likely origin is
  skill-implementation-workflow.md:233, which claims META.md sits alongside
  every skill when one exists in the whole tree.
- architecture.md said core/AGENTS.md is "deployed beside" CLAUDE.md.
  deploy-manifest.sh sends them to ~/.claude/ and ~/.agents/ respectively; the
  relation is import, not adjacency.
- gates.md's see-also cited ADRs as bare stems where its neighbours use paths.

Implementation notes: architecture.md's closing pointer sent readers to the
published description "for what a consumer actually gets", which was true
against an enumeration and is not after ADR-0021. It now names the boundary
relationship and points at the skills tree and README for an inventory. README's
bin bullet gains caveman and zoom-out, since ADR-0021 leaves it the only place
an inventory lives.

Impact: 16/16 pre-push hooks pass. Deliberately not fixed here and tracked
separately: the 12 pre-commit-stage hooks gates.md does not document, its own
SentenceOpenerThereIs violation, and README's missing scripts/install.sh step.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
fix(docs): correct claims the first fix round asserted without measuring d42f6368fe 
Why: two blind verifiers re-ran the five preceding commits and found four
defects of the same class this branch exists to close -- a confidently stated
measured claim that does not survive re-measurement -- this time inside the
fixes themselves.

- AGENTS.md:41 still carried both phrasings c68e864 reports having corrected.
  `grep -rn repo-defined` returned exactly one hit repo-wide: that line, in the
  file every session preloads. 4d336bb edited the line directly above it.
- ADR-0021 asserted twice, in the section justifying that no gate is added,
  that the ADR-0020 validators "never open an apm.yml". All three open and
  yaml.safe_load it (skill-size-check.sh:342, both validate.sh). The conclusion
  survives -- none reads the description: key, and their globs are SKILL.md and
  *.agent.md only -- but the stated mechanism is falsified by one grep.
- architecture.md said the ADR directory holds 20 numbered ADRs; c7ba3d2 made
  it 21, and c68e864 audited that file for exactly this class of stale count.
  The number is dropped rather than corrected: `ls docs/adr/` is already the
  index, so a count in prose is a second thing to maintain.
- gates.md's new three-verdict table said `-> name` promotes an unresolved
  target to ERROR. Reproduced with fixtures: NAME_HYPH (skill-size-check.sh:543)
  requires a hyphen, so `-> gitea-prs` is checked and `-> triage` is not
  extracted at all, and the unicode arrow is never recognised. The SUGGESTION
  text advises that spelling, so taking its advice can silence the finding. The
  gap is now documented as a defect; nothing covers it, since the one arrow case
  in test-adr0020-targets.sh happens to use a hyphenated target.

Implementation notes:
- AGENTS.md:48's coverage claim is shrunk rather than chased. Restoring six
  glossary entries did not make it true: 12 more sampled terms are undefined,
  three of them (trigger/capability/boundary clause) used inside CONTEXT.md
  itself. It now says CONTEXT.md is the glossary and is not exhaustive.
- CONTEXT.md's output profile and near-miss entries are corrected against their
  sources. The first stated a false exclusion -- .github/plugin/plugin.json IS
  apm-generated; only the marketplace mirror has no profile. The second
  inverted its source's referent: description-quality.md defines a near-miss as
  a query, not a sibling skill.
- The strict-mode message named jq, which no suite guards on (`command -v jq`
  appears nowhere in tests/), while omitting python3/PyYAML, which three do.
- README's git and gitea bullets now name git-workflow and gitea-workflow.
  ADR-0021 leaves README the only inventory and architecture.md now points at
  it, so the two bullets that were short had to be completed.
- ADR-0018's 2026-08-14 correction is marked superseded in place. It asserted
  machine state in the present tense that its own 2026-08-17 note retracts.
- ADR-0021's remaining errors: six files -> four (measured from de84d1b), the
  wiki description's length 114 -> 96 chars, the codex self-contradiction, the
  cost argument overstating bumps already owed for any skill addition, and two
  claims about files this branch went on to edit.
- The "15 of 17 suites" figure is restored where I had removed it: it is a dated
  record of one incident, not a live count, and four sites now describe it the
  same way.

Impact: 16/16 pre-push hooks pass, suite 24 passed 0 skipped 0 failed. No
behaviour change; every edit is prose or a comment.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
Claude commented 2026-08-17 13:30:59 +00:00
Author
Collaborator
Copy Link

Review round two: 11 defects found, all fixed, plus one reversed decision

A five-way review of this branch at de84d1b found 11 defects. Six commits (b1ea14d..d42f636) fix them. Two blind verifiers then re-ran the first five commits and found four more — fixed in d42f636.

Parts of the PR body above are now wrong. Corrections are in the "Body corrections" section at the bottom; read them before reviewing against it.

The one real bug

bd2bf66 restored the apm pack guard-rail by appending it to the Fix: command after --. That made the printed line stop being runnable, and it was worse than it looked. Reproduced by execution:

Fix: bash scripts/sync-marketplace-mirror.sh -- apm ships no output profile targeting this path, so `apm pack` does not refresh it. ...

Pasting that (a) command-substituted a real apm pack run via the unquoted backticks, then (b) hit -- as the POSIX end-of-options marker, so ${1:-} became --, CHECK stayed 0, no shift occurred, and [[ $# -eq 0 ]] || usage exited 1. The user got a usage error from the tool meant to fix their problem, and the mirror stayed stale. Fixed in b1ea14d; the command now stands alone on its own line, verified by pasting the printed output verbatim (exit 0, mirror synced, re-check clean).

Note tests/test-sync-marketplace-mirror.sh asserts nothing about the DRIFT message, so this can regress silently. Tracked separately.

The false-green risk

AGENTS.md instructed bash tests/run-tests.sh without --strict. That is precisely the invocation where a suite whose dependency is missing exits 77, reports SKIPPED rather than failed, and the run goes green having verified less than it claims — the failure .pre-commit-config.yaml:71 and gates.md both already record. Fixed in 4d336bb with the flag and a one-clause reason, so a future trim cannot drop it as noise.

Relatedly, tests/run-tests.sh:262 — the message a developer is handed at the moment a push gate fails — still cited AGENTS.md for the dependency list this branch moved to README.md. 56cc173 re-anchored four files of this class and missed the only one a human reads. Fixed in 3659659, verified by forcing the skip path with vale off PATH.

Reversed decision: ADR-0021, enumeration retired

The "published descriptions enumerate" rule this PR's body proposes has now failed three times, and the third failure is inside the correction for the second:

Plugin Skills Named Unnamed
bin 11 9 caveman, zoom-out
git 9 8 git-workflow
gitea 7 6 gitea-workflow

23 of 27 at the third attempt — and git-workflow is missing despite 65bac15's own message claiming it was added.

Critically, bb9158d (the August precedent this PR cites) was a wrong-content failure, not an incomplete list: core's description was a syntactically perfect four-item enumeration of bin's skills. Enumerating harder could not have caught it, and a gate asking "does every enumerated item exist?" would have passed it — all four existed. bb9158d's own fix replaced the enumeration with a domain boundary.

c7ba3d2 retires enumeration and records the decision in ADR-0021, including why no gate is added. Versions: bin 1.1.5, git 1.3.5, gitea 1.3.6, marketplace 0.4.5.

Also closed: root apm.yml's top-level version: was left at 0.4.2 while marketplace.version went to 0.4.4 — these have moved in lockstep in every commit that ever touched the file, and apm.yml's own comment records the top-level field as live and consumed by apm audit. No gate catches it: apm-pack-check-clean compares compiled output against apm.yml, not the two fields against each other.

Corrected factual claims

c68e864 and d42f636 fix claims that did not survive re-measurement:

  • gates.md cited docs/research/examples/; the tree is at plugins/kyberforge/docs/research/examples/
  • gates.md's description-budget arithmetic rested on 23,427, an ADR-0020 figure pinned to f9b919d, and compared a name-inclusive total against a description-only ceiling — dropped rather than re-measured, following this branch's own precedent for CONTEXT.md's token figure
  • gates.md listed "every routing target must resolve" as a hard FAIL. Verified with fixtures: SUGGESTION by default, ERROR only when terminal and route-notated or corroborated, INFO when no universe resolves
  • gates.md/README.md called pre-commit run --hook-stage pre-push --all-files the whole push gate. check-release-needed.sh is a no-op there — its own header calls this a "Known gap"
  • architecture.md claimed when: appears in two of 39 skill sources; exactly one SKILL.md carries it (the second hit is a META.md)
  • architecture.md said core/AGENTS.md deploys "beside" CLAUDE.md; they go to ~/.agents/ and ~/.claude/

Machine state removed from preloaded context

AGENTS.md told agents the <plugin>: form resolves "because user-scope native installs were left enabled on purpose". That premise is false here: installed_plugins.json is {"plugins": {}}, no enabledPlugins key exists in ~/.claude.json, ~/.apm/marketplaces.json is empty.

ADR-0018 had already reversed itself once on this exact claim (Correction 2026-08-14) citing that same enablement as evidence. Rather than flip it a third time, 4d336bb makes both files state nothing about install state, and ADR-0018 gets a dated note recording that this fact is machine state, not a property of the decision.

What the blind verifiers caught in the fixes themselves

Four defects of the same class this branch exists to close, found after the first five commits and fixed in d42f636:

  • AGENTS.md:41 still carried both phrasings c68e864 reports fixing — grep -rn 'repo-defined' returned exactly one hit repo-wide, in the preloaded file
  • ADR-0021 asserted twice, in the section justifying no gate, that the validators "never open an apm.yml". All three do (skill-size-check.sh:342, both validate.sh). The conclusion survives — none reads description: — but the mechanism was falsified by one grep
  • architecture.md said 20 ADRs; c7ba3d2 made it 21, in the file c68e864 audited for stale counts. Number dropped — ls docs/adr/ is already the index
  • gates.md's new verdict table said -> name promotes to ERROR. NAME_HYPH requires a hyphen, so -> gitea-prs is checked and -> triage is not extracted at all, and the SUGGESTION text advises that spelling — taking its advice can silence the finding. Documented as a defect; nothing covers it, since the one arrow case in test-adr0020-targets.sh happens to use a hyphenated target

AGENTS.md:48's coverage claim was shrunk rather than chased: restoring six glossary entries did not make it true (12 more sampled terms are undefined, three used inside CONTEXT.md itself).

Body corrections

  • No release tag is needed at merge. check-release-needed derives its pathspec solely from .pre-commit-hooks.yaml entries plus sibling assets/ — four paths, none touched here. And v2.0.0 already points at 9385c77, this PR's base. Cutting a tag "to satisfy the gate" would be cargo-culting
  • Versions: marketplace is 0.4.2 → 0.4.5 (not 0.4.3), and bin 1.1.3 → 1.1.5 is not mentioned in the body at all
  • The marketplace diff is not "exactly ten lines"; CONTEXT.md is not 9,762 B
  • The "published descriptions enumerate" rationale is reversed by ADR-0021
  • Gitea's API reports different line counts than git (+1330/−243 vs +1365/−278 at de84d1b) — review against git, not the web UI

apm.lock.yaml — a reviewer can skip the 350 lines

Every resolved_commit moves f9b919d → 9385c77: the lock catching up to content already merged in #103. No new or removed dependencies, no ref retargeting. lint losing exec_status: gated_pending_approval traces to 36ba7a1 (already on main), which removed its only approval-gated artifact ��� plugins/lint ships no executable at either commit. Not a trust downgrade. No consumer impact: this is the repo's own working-copy lock, and .claude/skills/ and .claude/agents/ are gitignored.

Verification at d42f636

  • pre-commit run --hook-stage pre-push --all-files → 16/16 Passed, exit 0
  • bash tests/run-tests.sh --strict → 24 passed, 0 skipped, 0 failed
  • Commit-stage pre-commit run --all-files fails on the documented ADR-0020 hot-gate baseline (26/9/10) — verified identical on main; these commits touch no SKILL.md, no skill-size-check.sh, no Vale style
  • Both marketplace.json mirrors byte-identical; description and version agree across all six locations per plugin

Caveat: d42f636 fixes what the blind verifiers found, but has not itself been through a blind verification pass.

Deferred to issues

gates.md's 12 undocumented pre-commit-stage hooks (incl. repo-local skill-frontmatter) · the -> name hyphenation gap and its missing test · test-sync-marketplace-mirror.sh pinning nothing about the DRIFT message · ADR-0013:98's wrong docs/research/examples/ path · skill-implementation-workflow.md:233's false "META.md alongside every skill" claim · gates.md's own SentenceOpenerThereIs violation · README's missing scripts/install.sh step · CONTEXT.md's 12 undefined terms.

Refs #99

## Review round two: 11 defects found, all fixed, plus one reversed decision A five-way review of this branch at `de84d1b` found 11 defects. Six commits (`b1ea14d..d42f636`) fix them. Two blind verifiers then re-ran the first five commits and found four more — fixed in `d42f636`. **Parts of the PR body above are now wrong.** Corrections are in the "Body corrections" section at the bottom; read them before reviewing against it. ### The one real bug `bd2bf66` restored the `apm pack` guard-rail by appending it to the `Fix:` command after `--`. That made the printed line stop being runnable, and it was worse than it looked. Reproduced by execution: ``` Fix: bash scripts/sync-marketplace-mirror.sh -- apm ships no output profile targeting this path, so `apm pack` does not refresh it. ... ``` Pasting that (a) command-substituted a **real `apm pack` run** via the unquoted backticks, then (b) hit `--` as the POSIX end-of-options marker, so `${1:-}` became `--`, `CHECK` stayed 0, no shift occurred, and `[[ $# -eq 0 ]] || usage` exited 1. The user got a usage error from the tool meant to fix their problem, and the mirror stayed stale. Fixed in `b1ea14d`; the command now stands alone on its own line, verified by pasting the printed output verbatim (exit 0, mirror synced, re-check clean). Note `tests/test-sync-marketplace-mirror.sh` asserts nothing about the DRIFT message, so this can regress silently. Tracked separately. ### The false-green risk `AGENTS.md` instructed `bash tests/run-tests.sh` without `--strict`. That is precisely the invocation where a suite whose dependency is missing exits 77, reports SKIPPED rather than failed, and the run goes green having verified less than it claims — the failure `.pre-commit-config.yaml:71` and `gates.md` both already record. Fixed in `4d336bb` with the flag and a one-clause reason, so a future trim cannot drop it as noise. Relatedly, `tests/run-tests.sh:262` — the message a developer is handed *at the moment a push gate fails* — still cited AGENTS.md for the dependency list this branch moved to README.md. `56cc173` re-anchored four files of this class and missed the only one a human reads. Fixed in `3659659`, verified by forcing the skip path with `vale` off PATH. ### Reversed decision: ADR-0021, enumeration retired The "published descriptions enumerate" rule this PR's body proposes has now failed three times, and the third failure is inside the correction for the second: | Plugin | Skills | Named | Unnamed | |---|---:|---:|---| | `bin` | 11 | 9 | `caveman`, `zoom-out` | | `git` | 9 | 8 | `git-workflow` | | `gitea` | 7 | 6 | `gitea-workflow` | 23 of 27 at the third attempt — and `git-workflow` is missing despite `65bac15`'s own message claiming it was added. Critically, `bb9158d` (the August precedent this PR cites) was a **wrong-content** failure, not an incomplete list: `core`'s description was a syntactically perfect four-item enumeration of `bin`'s skills. Enumerating harder could not have caught it, and a gate asking "does every enumerated item exist?" would have passed it — all four existed. `bb9158d`'s own fix replaced the enumeration with a domain boundary. `c7ba3d2` retires enumeration and records the decision in ADR-0021, including why no gate is added. Versions: `bin` 1.1.5, `git` 1.3.5, `gitea` 1.3.6, marketplace 0.4.5. **Also closed:** root `apm.yml`'s top-level `version:` was left at 0.4.2 while `marketplace.version` went to 0.4.4 — these have moved in lockstep in every commit that ever touched the file, and `apm.yml`'s own comment records the top-level field as live and consumed by `apm audit`. No gate catches it: `apm-pack-check-clean` compares compiled output against `apm.yml`, not the two fields against each other. ### Corrected factual claims `c68e864` and `d42f636` fix claims that did not survive re-measurement: - `gates.md` cited `docs/research/examples/`; the tree is at `plugins/kyberforge/docs/research/examples/` - `gates.md`'s description-budget arithmetic rested on 23,427, an ADR-0020 figure pinned to `f9b919d`, and compared a name-inclusive total against a description-only ceiling — dropped rather than re-measured, following this branch's own precedent for CONTEXT.md's token figure - `gates.md` listed "every routing target must resolve" as a hard FAIL. Verified with fixtures: SUGGESTION by default, ERROR only when terminal *and* route-notated or corroborated, INFO when no universe resolves - `gates.md`/`README.md` called `pre-commit run --hook-stage pre-push --all-files` the whole push gate. `check-release-needed.sh` is a no-op there — its own header calls this a "Known gap" - `architecture.md` claimed `when:` appears in two of 39 skill sources; exactly one `SKILL.md` carries it (the second hit is a `META.md`) - `architecture.md` said `core/AGENTS.md` deploys "beside" CLAUDE.md; they go to `~/.agents/` and `~/.claude/` ### Machine state removed from preloaded context `AGENTS.md` told agents the `<plugin>:` form resolves "because user-scope native installs were left enabled on purpose". That premise is false here: `installed_plugins.json` is `{"plugins": {}}`, no `enabledPlugins` key exists in `~/.claude.json`, `~/.apm/marketplaces.json` is empty. ADR-0018 had already reversed itself once on this exact claim (Correction 2026-08-14) citing that same enablement as evidence. Rather than flip it a third time, `4d336bb` makes both files state nothing about install state, and ADR-0018 gets a dated note recording that this fact is machine state, not a property of the decision. ### What the blind verifiers caught in the fixes themselves Four defects of the same class this branch exists to close, found after the first five commits and fixed in `d42f636`: - `AGENTS.md:41` still carried **both** phrasings `c68e864` reports fixing — `grep -rn 'repo-defined'` returned exactly one hit repo-wide, in the preloaded file - ADR-0021 asserted twice, in the section justifying no gate, that the validators "never open an `apm.yml`". All three do (`skill-size-check.sh:342`, both `validate.sh`). The conclusion survives — none reads `description:` — but the mechanism was falsified by one grep - `architecture.md` said 20 ADRs; `c7ba3d2` made it 21, in the file `c68e864` audited for stale counts. Number dropped — `ls docs/adr/` is already the index - `gates.md`'s new verdict table said `-> name` promotes to ERROR. `NAME_HYPH` requires a hyphen, so `-> gitea-prs` is checked and `-> triage` is not extracted at all, and the SUGGESTION text advises that spelling — **taking its advice can silence the finding**. Documented as a defect; nothing covers it, since the one arrow case in `test-adr0020-targets.sh` happens to use a hyphenated target `AGENTS.md:48`'s coverage claim was shrunk rather than chased: restoring six glossary entries did not make it true (12 more sampled terms are undefined, three used inside CONTEXT.md itself). ### Body corrections - **No release tag is needed at merge.** `check-release-needed` derives its pathspec solely from `.pre-commit-hooks.yaml` entries plus sibling `assets/` — four paths, none touched here. And `v2.0.0` already points at `9385c77`, this PR's base. Cutting a tag "to satisfy the gate" would be cargo-culting - **Versions:** marketplace is 0.4.2 → **0.4.5** (not 0.4.3), and `bin` 1.1.3 → **1.1.5** is not mentioned in the body at all - The marketplace diff is not "exactly ten lines"; `CONTEXT.md` is not 9,762 B - The "published descriptions enumerate" rationale is **reversed** by ADR-0021 - Gitea's API reports different line counts than git (`+1330/−243` vs `+1365/−278` at `de84d1b`) — review against git, not the web UI ### `apm.lock.yaml` — a reviewer can skip the 350 lines Every `resolved_commit` moves `f9b919d → 9385c77`: the lock catching up to content already merged in #103. No new or removed dependencies, no ref retargeting. `lint` losing `exec_status: gated_pending_approval` traces to `36ba7a1` (already on `main`), which removed its only approval-gated artifact ��� `plugins/lint` ships no executable at either commit. Not a trust downgrade. No consumer impact: this is the repo's own working-copy lock, and `.claude/skills/` and `.claude/agents/` are gitignored. ### Verification at `d42f636` - `pre-commit run --hook-stage pre-push --all-files` → **16/16 Passed, exit 0** - `bash tests/run-tests.sh --strict` → **24 passed, 0 skipped, 0 failed** - Commit-stage `pre-commit run --all-files` fails on the documented ADR-0020 hot-gate baseline (26/9/10) — **verified identical on `main`**; these commits touch no `SKILL.md`, no `skill-size-check.sh`, no Vale style - Both `marketplace.json` mirrors byte-identical; description and version agree across all six locations per plugin **Caveat:** `d42f636` fixes what the blind verifiers found, but has not itself been through a blind verification pass. ### Deferred to issues `gates.md`'s 12 undocumented pre-commit-stage hooks (incl. repo-local `skill-frontmatter`) · the `-> name` hyphenation gap and its missing test · `test-sync-marketplace-mirror.sh` pinning nothing about the DRIFT message · `ADR-0013:98`'s wrong `docs/research/examples/` path · `skill-implementation-workflow.md:233`'s false "`META.md` alongside every skill" claim · gates.md's own `SentenceOpenerThereIs` violation · README's missing `scripts/install.sh` step · CONTEXT.md's 12 undefined terms. Refs #99
Defame1297 approved these changes 2026-08-17 14:08:18 +00:00
Defame1297 merged commit 68e08c2413 into main 2026-08-17 14:08:24 +00:00
Defame1297 deleted branch docs/slim-agents-md 2026-08-17 14:08:24 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Defame1297
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Claude renovate-bot Defame1297
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Defame1297/holocron#105
Delete Branch "docs/slim-agents-md"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?