From cb0d959a4a5ab8e303c42e5777eb898ca5e11a6d Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 12:53:09 -0700 Subject: [PATCH 1/3] docs(agents): an ADR request in an issue or plan is still held to the bar Issues written before the ADR cleanup ask for "an ADR under dev-docs/adr" in their acceptance lists, and an agent following them wrote two records (bomly-cli ADR-0050 and ADR-0051) that failed the bar and were folded back into ADR-0020 and ARCHITECTURE.md in bomly-cli#531. The rule now says such a request asks for the decision to be recorded, not for a new file: the bar still decides, and a passing decision revises the live record that owns the topic first. The same section appears in both repositories and changes in both. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index bba02f97..575defee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -200,7 +200,7 @@ Runtime preparation is owned by `internal/engine`: build the filtered registry o - **Plugin protocol is versioned `v1`.** External plugins use the SDK/HashiCorp gRPC `Metadata` and role descriptor contract. - **No secrets or credentials in logs.** Ever. - **Matcher network calls require explicit enrichment.** Built-in matchers may contact OSV (`https://api.osv.dev`), CISA KEV, deps.dev (`https://api.deps.dev`), OpenSSF Scorecard (`https://api.scorecard.dev`), and Grype's database service (`https://grype.anchore.io/databases`, plus the archive URL it returns) only during `--enrich`. Installed external matcher plugins such as ClearlyDefined and endoflife.date may contact their documented services during `--enrich`. `--audit` evaluates existing package data and must not trigger matcher calls. Remote Git targets and build-tool detectors have separate, explicit network behavior. -- **An ADR records a decision, not an implementation.** Write one in [`dev-docs/adr/`](dev-docs/adr/README.md) only when a real alternative exists that someone would propose again, reversing the choice is expensive (an output or wire contract, a cross-repository or security boundary, a public claim), and the reason is not visible from the code or a guard's message. About 300 words, never more than about 400, one decision per file, with the rejected alternative and what enforces it; revise in place rather than appending amendments. Everything else is a code comment or a paragraph in `dev-docs/ARCHITECTURE.md`, which stays the architecture narrative (`docs/ARCHITECTURE.md` is the public overview). The full rule is [`dev-docs/adr/README.md`](dev-docs/adr/README.md). +- **An ADR records a decision, not an implementation.** Write one in [`dev-docs/adr/`](dev-docs/adr/README.md) only when a real alternative exists that someone would propose again, reversing the choice is expensive (an output or wire contract, a cross-repository or security boundary, a public claim), and the reason is not visible from the code or a guard's message. About 300 words, never more than about 400, one decision per file, with the rejected alternative and what enforces it; revise in place rather than appending amendments. An issue, plan or acceptance checklist that asks for an ADR is asking for the decision to be recorded, not for a new file, and the bar above still decides: when the decision fails it, the reasoning goes in a doc comment or `dev-docs/ARCHITECTURE.md` and the pull request says so; when it passes, revise the live record that owns the topic, and start a new one only when none does. Everything else is a code comment or a paragraph in `dev-docs/ARCHITECTURE.md`, which stays the architecture narrative (`docs/ARCHITECTURE.md` is the public overview). The full rule is [`dev-docs/adr/README.md`](dev-docs/adr/README.md). - **A format's specification outranks anything Bomly wrote.** When a specification and a Bomly document disagree about what a value in that format means, the specification wins — in every case, without being weighed against anything, accepted ADRs included. Bomly never got to decide what a word means in a format it does not own. Resolve such a question by citing the specification text, preferably as the pinned dependency vendors it (`cyclonedx-go` ships the CycloneDX schemas with their normative `meta:enum` descriptions), quote it in the code next to the behavior it settles, and correct whichever Bomly document was wrong. Neither "producers in the wild spell it loosely" nor "this direction is safer for a scanner" licenses a non-conforming reading: the first misreads every conforming document to accommodate the ones that are not, and the second is answered by a warning, a Bomly-owned policy knob that states plainly that it departs from the specification, or an upstream bug report. Worked examples, both in ADR-0037's scope rule and both resolved in bomly-dev/bomly-sdk#63: `optional` was read as runtime on a pre-1.6 gloss and defended as the safer reading for a scanner, and an absent scope — which CycloneDX says a consumer should assume is `required` — was read as no scope and dropped from every runtime filter. Reading the spec text once found both; another round of arguing the merits would have found neither. - **Prefer `internal/`.** Add new packages inside `internal/` unless there is a clear public API need; genuinely public contract surface belongs in the SDK module. - **Standard library + Cobra + existing deps only.** Do not add new dependencies without discussion. From 0bd99deed9daa85552ce597952f8da71c5ebfc3a Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 13:11:26 -0700 Subject: [PATCH 2/3] docs(adr): state the issue-request rule in the README the AGENTS.md summary points at Both AGENTS.md summaries end by naming dev-docs/adr/README.md as the full rule, so the full rule now carries the same sentence. The CLI summary uses "code comment", the term the sentence after it already uses. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- dev-docs/adr/README.md | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 575defee..918cd20a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -200,7 +200,7 @@ Runtime preparation is owned by `internal/engine`: build the filtered registry o - **Plugin protocol is versioned `v1`.** External plugins use the SDK/HashiCorp gRPC `Metadata` and role descriptor contract. - **No secrets or credentials in logs.** Ever. - **Matcher network calls require explicit enrichment.** Built-in matchers may contact OSV (`https://api.osv.dev`), CISA KEV, deps.dev (`https://api.deps.dev`), OpenSSF Scorecard (`https://api.scorecard.dev`), and Grype's database service (`https://grype.anchore.io/databases`, plus the archive URL it returns) only during `--enrich`. Installed external matcher plugins such as ClearlyDefined and endoflife.date may contact their documented services during `--enrich`. `--audit` evaluates existing package data and must not trigger matcher calls. Remote Git targets and build-tool detectors have separate, explicit network behavior. -- **An ADR records a decision, not an implementation.** Write one in [`dev-docs/adr/`](dev-docs/adr/README.md) only when a real alternative exists that someone would propose again, reversing the choice is expensive (an output or wire contract, a cross-repository or security boundary, a public claim), and the reason is not visible from the code or a guard's message. About 300 words, never more than about 400, one decision per file, with the rejected alternative and what enforces it; revise in place rather than appending amendments. An issue, plan or acceptance checklist that asks for an ADR is asking for the decision to be recorded, not for a new file, and the bar above still decides: when the decision fails it, the reasoning goes in a doc comment or `dev-docs/ARCHITECTURE.md` and the pull request says so; when it passes, revise the live record that owns the topic, and start a new one only when none does. Everything else is a code comment or a paragraph in `dev-docs/ARCHITECTURE.md`, which stays the architecture narrative (`docs/ARCHITECTURE.md` is the public overview). The full rule is [`dev-docs/adr/README.md`](dev-docs/adr/README.md). +- **An ADR records a decision, not an implementation.** Write one in [`dev-docs/adr/`](dev-docs/adr/README.md) only when a real alternative exists that someone would propose again, reversing the choice is expensive (an output or wire contract, a cross-repository or security boundary, a public claim), and the reason is not visible from the code or a guard's message. About 300 words, never more than about 400, one decision per file, with the rejected alternative and what enforces it; revise in place rather than appending amendments. An issue, plan or acceptance checklist that asks for an ADR is asking for the decision to be recorded, not for a new file, and the bar above still decides: when the decision fails it, the reasoning goes in a code comment or `dev-docs/ARCHITECTURE.md` and the pull request says so; when it passes, revise the live record that owns the topic, and start a new one only when none does. Everything else is a code comment or a paragraph in `dev-docs/ARCHITECTURE.md`, which stays the architecture narrative (`docs/ARCHITECTURE.md` is the public overview). The full rule is [`dev-docs/adr/README.md`](dev-docs/adr/README.md). - **A format's specification outranks anything Bomly wrote.** When a specification and a Bomly document disagree about what a value in that format means, the specification wins — in every case, without being weighed against anything, accepted ADRs included. Bomly never got to decide what a word means in a format it does not own. Resolve such a question by citing the specification text, preferably as the pinned dependency vendors it (`cyclonedx-go` ships the CycloneDX schemas with their normative `meta:enum` descriptions), quote it in the code next to the behavior it settles, and correct whichever Bomly document was wrong. Neither "producers in the wild spell it loosely" nor "this direction is safer for a scanner" licenses a non-conforming reading: the first misreads every conforming document to accommodate the ones that are not, and the second is answered by a warning, a Bomly-owned policy knob that states plainly that it departs from the specification, or an upstream bug report. Worked examples, both in ADR-0037's scope rule and both resolved in bomly-dev/bomly-sdk#63: `optional` was read as runtime on a pre-1.6 gloss and defended as the safer reading for a scanner, and an absent scope — which CycloneDX says a consumer should assume is `required` — was read as no scope and dropped from every runtime filter. Reading the spec text once found both; another round of arguing the merits would have found neither. - **Prefer `internal/`.** Add new packages inside `internal/` unless there is a clear public API need; genuinely public contract surface belongs in the SDK module. - **Standard library + Cobra + existing deps only.** Do not add new dependencies without discussion. diff --git a/dev-docs/adr/README.md b/dev-docs/adr/README.md index ea67294f..dcb4dfb2 100644 --- a/dev-docs/adr/README.md +++ b/dev-docs/adr/README.md @@ -27,6 +27,11 @@ documentation, and it goes next to the code. Before adding a record, check whether a live one already owns the topic and revise that one instead. +An issue, plan or acceptance checklist that asks for an ADR is asking for the +decision to be recorded, not for a new file, and these three tests still +decide. When the decision fails them, the reasoning goes in a code comment or +in [`../ARCHITECTURE.md`](../ARCHITECTURE.md), and the pull request says so. + ## How to write one Copy [`TEMPLATE.md`](TEMPLATE.md) to `NNNN-.md` with the From b46624ada3ef7a636a495b81f4bea54ec7f997f3 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 13:07:10 -0700 Subject: [PATCH 3/3] docs(agents): record criteria for plugin-author pages and developer docs The documentation style rules cover pages under docs/. Plugin-author pages, dev-docs/ARCHITECTURE.md paragraphs and AGENTS.md summaries had no written criteria, though the existing documents already follow consistent conventions. This records those conventions: - Plugin-author pages name the SDK's public API, which rule 5 would otherwise forbid, but never a CLI-internal identifier. - An ARCHITECTURE.md paragraph that carries reasoning below the ADR bar states the rule in the present tense with its reason, with no PR chronology, and links an ADR instead of restating it. - A rule AGENTS.md summarizes changes in its full-rule document in the same pull request. - The docs link check does not cover dev-docs/ or AGENTS.md, so links there are checked by review only. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 918cd20a..578fc80b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -384,6 +384,31 @@ Mechanics that go with the rules: `commands/`, `detectors/`, `matchers/`, `auditors/`, `plugins/`, `schemas/`. +### Plugin-author and developer documentation + +The rules above apply to every page under `docs/`. Three other kinds of +document follow these conventions: + +- **Plugin-author pages** (`docs/plugins/`) differ from rule 5 in one way. + They name the SDK's public API (packages, types, methods, descriptor + fields, manifest keys, requirement tokens), because that is what an + author writes. They never name a CLI-internal identifier. +- **`dev-docs/ARCHITECTURE.md`** describes how Bomly works today. A + paragraph there carries the reasoning for a choice that does not meet the + ADR bar in [`dev-docs/adr/README.md`](dev-docs/adr/README.md). It states + the rule in the present tense, gives the reason in the same paragraph, and + names identifiers only where the reader must go. It carries no + pull-request or release chronology, and it links an ADR instead of + restating it. +- **`AGENTS.md`** summarizes some rules and names the document that holds + the full rule, as the ADR bar names `dev-docs/adr/README.md`. A change to + such a rule lands in that document in the same pull request, so the + summary never states a rule the full text lacks. + +The `Docs link check` CI job covers `docs/`, `README.md` and +`CONTRIBUTING.md`. Links in `dev-docs/` and `AGENTS.md` are checked by +review only. + ### Fuzz tests - Every new or materially changed pure in-process parser for untrusted repository, configuration, baseline, SBOM, plugin, or analyzer data must have a native Go fuzz target. (The SDK's own parsers carry their fuzz targets in the SDK repo.)