docs: verify build output in the build, not by parsing it

[thecodedrift]

Two documentation changes, one commit each.

1. New convention: verify build output in the build (.conventions/STYLEGUIDE-CODE.md)

A new Testing section, stating the rule in three parts:

• A failing build is still a valid test — of the build. When an invariant is about a build artifact, enforce it where the artifact is produced. If a bundle must not contain something, the build should refuse to emit it rather than emitting it and leaving a test to go looking. An invariant enforced at production time cannot be violated; one enforced afterwards can only be detected.
• Tests that use a built artifact are fine. Importing the built entry and asserting on behavior, or spawning the built CLI and asserting on output, are ordinary tests. The rule is not "tests must not touch build output."
• Tests that parse build output are brittle and should be avoided. Re-deriving a fact from generated text reconstructs something the generator already knew, with a worse tool.

Folded in is the rule that prompted this: do not add a dependency in order to test an assertion. A test that needs a parser to make sense of an artifact is a test in the wrong place.

Worked example (the real case)

packages/cli/test/prompts.test.ts asserted that the built dist/prompts.js chunk graph never reaches the CLI entry or a host capability, by regex-scanning the built JavaScript for from "…" to reconstruct the import graph. A built chunk embeds every help recipe as a string literal, and the engine-selection recipe contains the phrase a different axis from "which engine" — so the scan reported dist/prompts.js graph imports which engine. Prose read as an import.

The rejected fixes are in the section as a table:

• Filtering by specifier shape passed only because that phrase contains a space. Measured against the real bundle, differs from "static-tier" is a bare hyphenated name with no whitespace and would still have been reported. The guard held by luck of punctuation.
• Adding es-module-lexer parsed the graph correctly but bought a dependency — and a second major version, since vite already pulls 1.7.0 transitively — to serve a single test.
• Anchoring the regex to line-start matched the lexer exactly on today's bundles, but required from on the same line as import. A future bundler wrapping a long import would silently stop detecting real imports — trading a loud false positive for a quiet false negative, in the guard whose entire job is catching a leak.

The resolution: rollup's OutputChunk already exposes imports and dynamicImports — the exact resolved graph. The check moves into a vite plugin that fails the build, and the test is deleted.

The section generalizes past the anecdote: the same reasoning forbids a YAML parser to assert on generated config, or an HTML parser to assert on rendered output. In each case the generator knows the answer and the test is guessing at it.

This PR documents the convention only — no code changes.

2. Please look at this separately: a dead instruction removed from CLAUDE.md

The top Code Standards section pointed at three files under .claude/. None of the three exist. The same document already links @.conventions/STYLEGUIDE-CODE.md correctly further down under Code Quality Checks, so CLAUDE.md contradicted itself about where the guide lives.

Line	Before	After
Code Style Guide	@.claude/STYLEGUIDE-CODE.md (missing)	@.conventions/STYLEGUIDE-CODE.md
UI Conventions	@.claude/STYLEGUIDE-UI.md (missing)	@.conventions/STYLEGUIDE-UI.md
File Naming Conventions	@.claude/FILE-CONVENTIONS.md (missing)	line removed

The removed line is the one worth a look. Searching the repo for any file serving a file-naming-conventions role turned up nothing — the only occurrence of the string FILE-CONVENTIONS anywhere is that dangling reference itself. Rather than invent the file, the line is deleted; authoring a new one is out of scope here. This was raised with the repo owner and the removal is a decision already taken, recorded here so it is visible in review rather than silent in a diff. If a file-naming convention should exist, it wants its own PR.

Checks

pnpm lint passes; prettier ran via lint-staged. Markdown only — nothing under packages/, openspec/, or .changeset/ is touched, hence skip-changeset.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jwc9FFroR3mTZ4hLiSkkX3

[Copilot]

Pull request overview

This PR updates repository documentation to establish and clarify conventions around testing build artifacts, and to remove stale/incorrect references in contributor guidance.

Changes:

• Adds a new Testing section to .conventions/STYLEGUIDE-CODE.md recommending enforcing build-artifact invariants inside the build (and avoiding tests that parse generated output).
• Updates CLAUDE.md to point “Code Standards” links at the existing .conventions/ style guides and removes a dead reference to a non-existent file-naming conventions doc.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
CLAUDE.md	Fixes “Code Standards” links to reference the actual .conventions/ guides; removes a dead .claude/ reference.
.conventions/STYLEGUIDE-CODE.md	Documents a new testing convention: enforce build-output invariants at build time rather than regex/parsing generated artifacts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.