Skip to content

#1165 Make a vetted subset of the library declarable - #1207

Merged
williamthorsen merged 16 commits into
mainfrom
1165
Aug 5, 2026
Merged

#1165 Make a vetted subset of the library declarable#1207
williamthorsen merged 16 commits into
mainfrom
1165

Conversation

@williamthorsen

@williamthorsen williamthorsen commented Aug 5, 2026

Copy link
Copy Markdown
Owner

What

Vetted guidance artifacts (skills, subagents, and rulebooks) are now organized into two nascent collections: recommended (generally applicable) and williamthorsen (the maintainer's personal rulebooks). The triage collection contains all unvetted guidance. The all set continues to deploy all guidance.

Why

collections.use: [all] was the only declaration that deployed a usable set, so a consumer took the whole catalog including artifacts they had no use for. Anything narrower deployed almost nothing, and no collection said anything about why its members belonged to it, so there was nothing to choose between.

Details

🎉 Features

  • recommended is now the vetted general set, williamthorsen the vetted personal set, and triage the default home for content nobody has read yet. Each collection body states what its membership claims and why each member qualifies.
  • Collections enumerate every member rather than their dependency roots. Roots-only membership would let an unexamined artifact enter through an edge and be treated as examined, which is the outcome the closure check exists to prevent.
  • The criteria deciding an artifact's disposition are recorded in the codeassembly-content-specification rulebook (version 7 → 8), so promoting an artifact is a delegable act rather than a judgment re-derived each time. The criteria name two reading passes, because environment coupling hides in a default value rather than in prose and survives a read that looks only for doctrine.
  • An artifact in no collection is standalone: deliberate, declared directly where wanted, and too rarely invoked to repay a standing line in the skill index. canary, codeassembly-content-specification, and migrate-feedback-memories start there.

🐛 Bug fixes

  • init --global seeds recommended and triage, and its comment explains what each collection claims.
  • common-mistakes, design-and-plan, and wrap-up declare edges for the skills their prose names, so those skills survive a declaration narrower than all.
  • capture-event documents the kb.yaml registry prerequisite alongside its Node version floor, so a reader learns of it before invoking rather than on refusal.
  • Four enforcement notes in the content specification named test files without their tier suffix.

🧪 Tests

  • A coverage check fails when an artifact carries no disposition, more than one, or a disposition naming an artifact the library no longer holds.
  • A closure check fails when a vetted collection reaches an artifact of lesser standing, and when any collection's closure reaches a standalone artifact. Standalone buys a skill-index line nobody pays for unless they ask, and that survives only while no closure reaches the artifact.
  • Both checks run against fixture content roots that reproduce the failures, and assert on message text so a message that stops naming the artifact fails.

🤖 Agentic support

  • AGENTS.md states that the repository is public, and that the package manifests' private: markers describe registry publication rather than who can read the source.

📚 Documentation

  • The package README describes the four shipped collections and the claim each carries, and points at the rulebook holding the promotion criteria.
  • all documents that it is the escape hatch rather than the expected declaration: it deploys the vetted, the unexamined, and the deliberately omitted alike, and a new artifact joins it before anyone has read it.

Closes #1165

@williamthorsen williamthorsen added breaking Breaking API change or removal of functionality feature Added or improved external functionality scope:agents labels Aug 5, 2026
@github-actions

github-actions Bot commented Aug 5, 2026

Copy link
Copy Markdown

Dependency audit

Production dependency audit passed.

Records the criteria that decide whether an artifact belongs in a public collection, a personal one, or neither, so an authoring agent applies them rather than re-deriving the judgment.

States vetting as two reading passes: the prose read for personal doctrine, then a second pass asking what the artifact names that exists only in the author's environment. Coupling hides in a default value or an example, where the first pass passes it over.
Declaring a skill that points a reader at another deploys the one it points at: `development-workflows`, `save-artifact`, `testing-conventions`, and `typescript-testing-conventions` join the closure of every caller that names them. Previously a prose mention created no edge, so a declaration narrower than the whole catalog dropped them.
Three collections replace the all-or-nothing choice between the whole catalog and a three-artifact proof set: `recommended` holds what is generally applicable, `williamthorsen` what is deliberately personal, and `triage` what nobody has examined yet. Declaring all three deploys everything `all` deploys, less the artifacts deliberately left out of every collection.

`recommended` drops `capture-feedback`, `people-report`, and `canary` and gains `capture-event`. The first two are personal; the third proves a mechanism and is wanted once rather than at every session.

`all` states that it is the whole-catalog escape hatch rather than the expected declaration.
Covers the two invariants the collection dispositions rest on: every library artifact is claimed by exactly one collection or recorded standalone, and a vetted collection's dependency closure reaches nothing of lesser standing. A new artifact, a promotion that forgets to remove the old claim, and a deletion that leaves its claim behind each fail with a message naming the artifact and what it lacks.
Asserts that a real deploy of the public collection lands the artifact it claims and none of the proof-of-mechanism bundle it replaced, so the set cannot grow back through a presence-only assertion.
Lists the `kb.yaml` registry among `capture-event`'s runtime dependencies, so an agent learns that `--store` resolves through `.agents/kb.yaml` or `~/.agents/kb.yaml` before composing a capture rather than on the refusal.
Names the repository's visibility in the project guidance, so an agent deciding what may be committed reads the answer rather than inferring it from the `private: true` markers on the package manifests, which govern registry publication alone.
`codeassembly init --global` scaffolds `~/.agents/codeassembly.yaml` declaring `recommended` and `triage`, and offers `williamthorsen` as a commented line, so a new machine starts from collections that carry a claim rather than from the whole catalog. Declaring `all` stays available for taking the catalog whole.

The personal collection is offered rather than seeded: a tool that declared it by default would assert general fitness for content examined and found fitted to one author.
Declaring `common-mistakes` deploys `commit` and `review-criteria`, the two skills its body sends a reader to that it did not yet name as dependencies.
The README names each shipped collection and the claim its membership makes, and states that an artifact in none of them is standalone. It points at the rulebook holding the criteria that decide which disposition an artifact takes.
Covers the guarantee that a standalone artifact deploys only where it is declared directly: an edge from any collection into one fails, naming the artifact. The vetted-closure rules constrained two collections, leaving the 71-member unexamined set free to reach a standalone artifact through a new edge.
The specification's enforcement notes name the files as they exist, so a reader can find each one and tell which `nmr test:*` tier runs it.
The comment on the standalone assertion states the constraint in the direction the closure runs: a collection reaches an artifact, not the reverse.
`read-vibelassian-conversation` no longer ships, and `williamthorsen` no longer carries it. The skill read the SQLite database of one workplace's internal tool, which no consumer of a public library can reach.

Removal stops the repository from shipping the internal path the skill named; the path stays readable in this public repository's history, so treat it as disclosed rather than withdrawn.
`codeassembly init --global` scaffolds a declaration naming `recommended` and `triage` alone. A reader who wants a personal collection adds it themselves.

The template's guidance names the two seeded collections and points at `all` for the whole catalog, leaving the reader to discover what else the library or a source ships.
The README states that `codeassembly init --global` seeds `recommended` and `triage`, and that any other collection is the reader's to add.
@williamthorsen
williamthorsen marked this pull request as ready for review August 5, 2026 17:07
@williamthorsen williamthorsen removed the breaking Breaking API change or removal of functionality label Aug 5, 2026
@williamthorsen williamthorsen self-assigned this Aug 5, 2026
@williamthorsen
williamthorsen merged commit 8f59b50 into main Aug 5, 2026
3 checks passed
@williamthorsen
williamthorsen deleted the 1165 branch August 5, 2026 17:15
williamthorsen added a commit that referenced this pull request Aug 7, 2026
…ssembly-mcp-v0.2.4 codeassembly-v0.6.0

codeassembly-v0.6.0
- #794 feat: Guide kb-add note placement with the store's declared taxonomy (#1223)
- #1111 feat: Declare which harnesses sync targets (#1221)
- #1214 feat: Allow an artifact to belong to more than one collection (#1219)
- #1186 drop!: Dissolve `common-mistakes` into its consumers' guidance (#1217)
- deps: Upgrade all deps to latest version
- #1203 fix: Bar acceptance-criteria revision prompts to genuine conflicts (#1212)
- #1196 feat: Add the .kb/taxonomy.yaml format with drift reporting and back-fill (#1210)
- #1165 feat: Make a vetted subset of the library declarable (#1207)
- #1197 feat: Report the retired `harnesses:` frontmatter key from `validate` (#1204)
- #963 feat!: Rename the harness id to rovo and qualify the frontmatter key (#1199)
- #1188 drop!: Retire the bundled Bitbucket inline-comment script (#1198)
- #1187 feat: Gate the boolean prefix on a test and add the tail rule it rests on (#1195)

factory-v0.2.4
- deps: Upgrade all deps to latest version
- deps: Upgrade all deps to latest version
- #1209 refactor: Clear factory's remaining lint violations and retire both deferral lists (#1216)
- #1208 refactor: Clear the visualizations lint violations and retire six rule deferrals (#1213)

kb-v0.4.0
- #794 feat: Guide kb-add note placement with the store's declared taxonomy (#1223)
- #1196 feat: Add the .kb/taxonomy.yaml format with drift reporting and back-fill (#1210)

codeassembly-lifecycle-v0.3.0
- #963 feat!: Rename the harness id to rovo and qualify the frontmatter key (#1199)

codeassembly-mcp-v0.2.4
- #1206 refactor: Retire fleet's lint deferrals (#1211)
- #1200 tooling: Retire mcp's lint deferrals and prune the dead root entries (#1205)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature Added or improved external functionality scope:agents

Projects

None yet

Development

Successfully merging this pull request may close these issues.

recommended collection is a stub, so the only usable declaration is collections.use: all

1 participant