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

docs(adr): record the review outcomes for the Research registry grammar

Browse Source 
- ADR-0004: add the "Amended by ADR-0028" note, following the ADR-0025
  convention.
- ADR-0028: correct Q5 (parse_status is gone), the skill count (38, not
  39), and the question order. Q7 records the anchored, format-only sha
  check. Q8 records the decision to commit real Vale fixtures. A new
  consequence covers path confinement and list rejection.
- CONTEXT.md: the `_Avoid_` entry means the bare noun, not the field.
- gates.md: correct the authored-hook counts after the corpus gate.
- create.md: a `none` entry backed by a reproduction must name committed
  fixtures in `Basis:`; use the `(digest: <full path>)` form.
- gitea-releases: use the `(digest: <full path>)` form.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EGHFJextYtVQseaHPDDhxB
This commit is contained in:
Defame1297
2026-09-21 19:40:43 +00:00
parent c008da1876
commit 58a3f402a6
6 changed files with 40 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/adr/0028-research-doc-names-the-research-registry.md
View File

@@ -9,8 +9,8 @@ whose `## H2` headings are the source slugs. The corpus did something else: 29 o
entries pointed at a research topic doc annotated `(whole-document reference)`, and 6 values were not
a single path (comma-separated lists and shell brace expansion, plus a semicolon pair in
`gitea-releases`). Checks 7 and 8 of `validate-provenance.sh` look the slug up as an H2 in the named
file, so 36 entries reported INFO and nothing failed. Measured by running the script over all 39 skill
directories, since nothing else runs it over the corpus.
file, so 36 entries reported INFO and nothing failed. Measured by running the script over all 38 skill
directories (27 with a `references/sources.md`, 11 without), since nothing else runs it over the corpus.
We decided that `Research doc:` names exactly one **Research registry** (the term is in
`CONTEXT.md`), as the spec always said. Slug-to-H2 lookup in the registry is the only provenance link
@@ -56,6 +56,17 @@ pairs are rejected outright, since nothing expands them in a markdown field.
- **(c) Everything FAIL (rejected).** Fails a correctly-provenanced skill audited from a deployed
copy, which the file-structure exemption exists to prevent.
**Q4 — enforcement.** A corpus-wide sweep gate lands in the same change: a test or pre-push hook that
runs `validate-provenance.sh` over every `plugins/*/.apm/skills/*/` and fails on any FAIL. Deferring it
was rejected because without a caller the FAIL tier is inert; nothing but `check-scope-walkup-sync.sh`
(on fixtures) invokes the validator today.
**Q5 — parser parity.** `parse_research_doc` accepts the bullet spelling (`- **Research doc:**`) as
`parse_contributing_files` already does, with a regression test. `parse_status` was removed from the
validator during this change, so it gets no test. Included because it is the same failure shape as
#111 and #118 (a parser returns "nothing found", the caller reads it as "nothing declared"), sits in
the same file, and `gitea-releases` already writes the unhyphenated form.
**Q6 — what happens to check 8.** Found unsatisfiable during the migration, after Q3 was decided.
Check 8 requires every `extracted` slug in the research doc to appear in the skill's `sources.md`.
That worked while entries pointed at topic docs, and was dormant. Under Q1(a) the named file is a
@@ -77,8 +88,10 @@ check on every `Basis:` bullet would fail them.
- **(a) A bullet annotated `(removed in <sha>)` skips the existence check (chosen).** The check stays
for live paths, which is what catches a renamed ADR, and deletion becomes an explicit, auditable
annotation. Weakness: the annotation can be written on any bullet to avoid the check. Verifying the
sha with `git cat-file -e` would close that, and was left out as over-engineering for three bullets.
annotation. The annotation is anchored at the end of the value and the sha is 7-40 hex characters.
Weakness: the annotation can be written on any bullet to avoid the check. Verifying the sha with
`git cat-file -e` would close that; the user decided against it as over-engineering for three
bullets, so the sha is format-checked only, not verified.
- **(b) `Basis:` becomes free prose with no existence check (rejected).** Gives up the one check that
catches a renamed or moved ADR.
- **(c) Drop those `Basis:` lines and keep `none` with a prose reason (rejected).** Loses the
@@ -92,13 +105,15 @@ fixtures in this repo". No such fixture or test exists in the tree or in history
in `d1afdbe` with no test files, and the only vale test ever deleted (`4de5b6b`) guards an unrelated
`E100`. Under Q2 it FAILed for a missing `Basis:`.
- **(e) Remove the entry and its `source_keys` citations (chosen).** The stated basis was false, so
there is nothing honest to declare. The behavioural rules stay in the skills; only the provenance
claim goes. The gate needs no allowlist.
- **(e) Remove the entry and its `source_keys` citations (chosen, as the interim state).** The stated
basis was false, so there is nothing honest to declare. The behavioural rules stay in the skills;
only the provenance claim goes. The gate needs no allowlist.
- **(a) `Basis: tests/test-vale-wrap.sh` (rejected).** Backs about one of six claims and overstates the
rest.
- **(b) Commit reproduction fixtures (rejected for now).** The right fix if the behaviours matter, but
separate work from this issue.
- **(b) Commit reproduction fixtures (chosen, supersedes the interim removal).** The user decided to
commit real Vale reproduction fixtures under `plugins/lint` rather than soften the wording. The
`house-vale-3-15-2-repro` claim is restored only once it is backed by committed fixtures, and it
names them via `Basis:` (with `Research doc: none`). Until they land, the claim stays absent.
- **(c) Allow `none` without `Basis:` for "house-verified" entries (rejected).** Reopens Q2 and gives
an escape hatch for unverified claims.
- **(d) Keep the entry and allowlist the two skills in the gate (rejected).** Keeps a false claim in
@@ -107,16 +122,6 @@ in `d1afdbe` with no test files, and the only vale test ever deleted (`4de5b6b`)
`configuration-reference.md` still says its rows were "reproduced against Vale 3.15.2"; that wording
now has no provenance entry behind it and is left for a separate decision.
**Q4 — enforcement.** A corpus-wide sweep gate lands in the same change: a test or pre-push hook that
runs `validate-provenance.sh` over every `plugins/*/.apm/skills/*/` and fails on any FAIL. Deferring it
was rejected because without a caller the FAIL tier is inert; nothing but `check-scope-walkup-sync.sh`
(on fixtures) invokes the validator today.
**Q5 — parser parity.** `parse_status` and `parse_research_doc` accept the bullet spelling
(`- **Status:**`) as `parse_contributing_files` already does, with a regression test. Included because
it is the same failure shape as #111 and #118 (a parser returns "nothing found", the caller reads it as
"nothing declared"), sits in the same file, and `gitea-releases` already writes the unhyphenated form.
## Consequences
- About 40 `references/sources.md` entries migrate: roughly 30 repoint from a topic doc to the registry,
@@ -133,4 +138,6 @@ it is the same failure shape as #111 and #118 (a parser returns "nothing found",
its mention from `skill-file-structure.md` and `create.md` where present.
- The corpus-wide sweep is a new gate: register it in `docs/spec/gates.md` and
`.pre-commit-config.yaml`. The corpus must be migrated in the same change or the suite goes red.
- The validator rejects an absolute path or one that escapes the repo with `..` in `Research doc:` and
`Basis:`, and rejects a `Research doc:` value with internal whitespace, backticks, or a comma list.
- Reversing this means re-migrating the same entries, which is why it is recorded.