Skip to content

docs(agents): record criteria for plugin-author pages and developer docs - #535

Closed
bomly-guy wants to merge 1 commit into
mainfrom
claude/docs-criteria-924994
Closed

bomly-guy wants to merge 1 commit into
mainfrom
claude/docs-criteria-924994

Conversation

@bomly-guy

Copy link
Copy Markdown
Collaborator

Related: #531 (its docs were reviewed against these criteria), #534.

Why

AGENTS.md has detailed rules for pages under docs/ (Documentation style, rules 1-10) and for ADRs (dev-docs/adr/README.md). It has none for three other kinds of document that #531 and #534 change:

What

A new subsection, "Plugin-author and developer documentation", under Quality Bar, right after Documentation style. Each line records a convention the existing documents already follow:

Document Criterion Derived from
docs/plugins/ Names the SDK's public API, never a CLI-internal identifier Every existing docs/plugins/*.md page
dev-docs/ARCHITECTURE.md Present-tense rule plus its reason, identifiers only where the reader must go, no PR or release chronology, links an ADR instead of restating it The document's own opening ("how Bomly is structured today"); adr/README.md and TEMPLATE.md ("No implementation history", "identifiers only where the reader must go")
AGENTS.md A rule it summarizes changes in its full-rule document in the same PR The ADR bullet's "The full rule is ..." and docs style rule 9 (one home per rule)

It also says which documents CI checks for links. The Docs link check job covers docs/, README.md and CONTRIBUTING.md, so links in dev-docs/ and AGENTS.md are checked by review only.

This change has no bomly-sdk companion. The new subsection applies only to bomly-cli documents and does not touch the shared ADR section or the AI review triage section, which are the ones marked "change both together".

Verification

  • make test passed, and the pre-commit hook's fmt-check and lint passed.

🤖 Generated with Claude Code

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 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Oct 25, 2026

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 28 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration
Commits

Reviewing files that changed from the base of the PR and between 67be1d0 and 18d9263.

Files selected for processing: 1
  • AGENTS.md
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review 🔄 Running since 2026-10-25T20:09:51.477110Z 18d9263 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

Copy link
Copy Markdown
Contributor

Bomly Diff Summary

Compared 67be1d087f514d750c6da373e85576b8356ba798 to 18d92631adbd05ed8a470c0f18ebe3f801ac77bd.

Overview

Status Manifests Dependencies Findings Duration
✅ Pass +0 / ~0 / -0 0 added / 0 version changed / 0 detail changes / 0 removed 0 introduced / 0 persisted / 0 resolved 1m 11s

Dependency Changes

✅ No dependency changes.

Vulnerabilities

✅ No vulnerability changes.

License Changes

✅ No license changes.

Project Posture

✅ No project posture changes (--matchers +scorecard was not selected).

Policy Findings

✅ No policy differences were identified.

bomly-guy added a commit that referenced this pull request Oct 25, 2026
…losure

- ADR-0050 returns as a retired stub: it was live on main, and numbers and
  filenames are kept. The index lists it under Retired (29 stubs).
- ADR-0020 has one Revised line, a Context sentence on plugin trust, and an
  accurate account of when the access block is shown: at install and in
  plugins info; plugins enable shows it but asks for no confirmation.
- PLUGINS.md lists every case that stops a run with exit 4 (as preflight's
  available() decides it), links the exit code and the SBOM glossary entry,
  says an omitted access list equals an empty one, and drops the circular
  "compare with what the plugin says".
- EXIT_CODES.md gains the preflight case under exit 4.
- The authoring guide links the prerequisites section inline and shows how
  a Go descriptor declares Requires.

Refs #535

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bomly-guy

Copy link
Copy Markdown
Collaborator Author

Folded into #534 at the user's request: commit 18d9263 is cherry-picked there as b46624a, unchanged. Both PRs edit AGENTS.md's documentation guidance, so they land as one.

🤖 Generated with Claude Code

@bomly-guy bomly-guy closed this Oct 25, 2026
bomly-guy added a commit that referenced this pull request Oct 25, 2026
…ccess (#531)

* build(deps): adopt bomly-sdk v0.16.0, giving embedded components a lifetime scope

v0.15.0 added HostContext.OnCleanup. Each embedded component now gets a
plugin.ComponentScope that RegisterModule records before the
constructor runs, and Registry.Close ends them newest first with joined
errors. Threading the command context and closing the registry at
command end follow in this pull request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(engine): preflight declared component requirements before a stage runs

Each stage now compares the requirements a component's descriptor declares
(bomly-sdk v0.16.0 plugin.Requirements) with what the host can vouch for:
source-tree-v1 for a filesystem or Git target not planned as an SBOM
document, dependency-graph-v1 once detection found a dependency node, and
vulnerability-records-v1 at analyze and audit once the registry carries a
record. A token this host cannot evaluate is never satisfied.

Before any stage, an explicitly selected component the plan can never run
fails the command with a PreflightError (exit 4) naming the component, the
requirement and the remedy. Inside a stage, a component whose requirement
the actual data misses is held back through a registry view before Ready is
called, with a warning on the stage's channel. Components that declare
nothing are untouched, and Ready/Applicable stay authoritative for the rest.

engine.go is not touched: the hook lives in pipeline.go around the existing
engine calls.

Refs #417

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(plugins): disclose declared access and requirements in plugin views

A package manifest may now carry the SDK's access block (bomly-sdk
v0.16.0 plugin.Access), validated only through plugin.ValidateAccess. A
malformed block fails the install; an absent one keeps installing and reads
as unknown, never as "no access". Install, enable (before the plugin is
enabled), info, verify and doctor show it as the publisher's unverified
claim through one renderer, and the JSON views carry it with
accessDisclosure set to declared or unknown. Nothing is enforced.

Declared requirements appear in `plugins info` (unknown tokens marked) and
in generated matcher, auditor and detector-chain pages when a component
declares any; no built-in does yet, so the generated docs are unchanged.

The installed-snapshot comparison now includes requirements, so a binary
whose declared requirements changed since install fails verify, and the
descriptor clone helpers delegate to the SDK's Clone, which copies them.

Refs #417
Refs #418

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: ADR-0051 and plugin docs for component prerequisites and declared access

ADR-0051 records the requirement vocabulary the host evaluates, unknown
tokens, explicit-versus-default failure, why provider names are not a
requirement, and disclosure without enforcement. docs/PLUGINS.md gains
"Component prerequisites" and "Declared access"; the authoring guide lists
the access keys and the descriptor's requires list.

Closes #417
Closes #418

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(engine): preflight ecosystem-scoped auditors in a component audit

explain's component audit selects auditors by the queried package's
ecosystem, but preflight listed them with no ecosystem, so an npm-only
auditor was neither checked at planning nor held back before Ready. The
plan now sees every auditor the filter selects, and the component-audit
stage evaluates the same selection the engine makes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: address CodeRabbit round 1 on preflight and access disclosure

- explain reports a preflight skip once, not once per matching manifest.
- LoadRuntimePlugins sets accessDisclosure like the other installed loaders.
- An absent access block reads "has no access declaration", which cannot be
  mistaken for an empty declaration.
- PLUGINS.md and the authoring guide state when Ready and Applicable run,
  and what a refused install says; ADR index count and ADR-0051 trimmed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(adr): fold ADR-0050 and ADR-0051 into existing records

Neither record met the ADR bar: ADR-0050's reason already lives in
Engine.Match's doc comment and the SDK Clone docs, and ADR-0051 mostly
described the code and restated ADR-0040's ownership split. Both are
deleted. ADR-0050 landed with #532 and nothing relied on it, so it has no
retired stub.

The two points that pass the bar move to existing homes. ADR-0020, the live
trust record, is revised in place: a manifest access block is the
publisher's unverified claim, shown before enabling and never enforced.
dev-docs/ARCHITECTURE.md (Scan Pipeline) now records why only a plan that
can never be satisfied fails the command, and why each matcher and analyzer
call works on its own snapshot. Code references point there; the ADR index
is back to 21 live records.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(plugins): state the outcome for an unknown requirement

A component selected by name with a requirement this Bomly does not know
stops the command with exit code 4; a default one is skipped with a warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: apply the docs-criteria review to prerequisites and access disclosure

- ADR-0050 returns as a retired stub: it was live on main, and numbers and
  filenames are kept. The index lists it under Retired (29 stubs).
- ADR-0020 has one Revised line, a Context sentence on plugin trust, and an
  accurate account of when the access block is shown: at install and in
  plugins info; plugins enable shows it but asks for no confirmation.
- PLUGINS.md lists every case that stops a run with exit 4 (as preflight's
  available() decides it), links the exit code and the SBOM glossary entry,
  says an omitted access list equals an empty one, and drops the circular
  "compare with what the plugin says".
- EXIT_CODES.md gains the preflight case under exit 4.
- The authoring guide links the prerequisites section inline and shows how
  a Go descriptor declares Requires.

Refs #535

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(engine): an SBOM beside source manifests leaves a source tree

Discovery plans an SBOM found in a directory as its own subproject next to
the directory's lockfiles, and any such subproject made preflight treat the
whole target as an SBOM document, skipping or rejecting components that
need source-tree-v1. A target is now an SBOM document only when every
planned subproject is one, as with --sbom.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant