An open source design system that's fully customizable and agent ready
TypeScript
spec(cli-surface): INV35 binds from the first stable integration check; DEC-8 doc-quality findings fail --strict (#7743)
Joey6fddf4f253d2
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.mdindex c7de8ca3d0..57adbea187 100644--- a/docs/architecture/cli-surface.md+++ b/docs/architecture/cli-surface.md@@ -173,17 +173,24 @@ and remains available through explicit Core package selection.integration manifest or a comparison that needs the project's TypeScript,reporting each as an error from the same findings the default run reports(INV32). An item a comparison lists as unchecked,- such as a prop type it cannot read, does not fail `--strict`. Its exit codes- and JSON shape are a compatibility contract for the builds that run it: a new- check, or a new failure code, MAY join it only in a minor release that names- the addition. A name a patch release adds to Core or the CLI (a component,- template, or topic) MAY raise a conflict with a package's own name. Each- `doctor integration` subcommand, exit code, and JSON MUST stay unchanged.- Because builds fail on its findings, it MUST NOT report a finding the- package's code does not contradict: a check that cannot judge an item lists- it as not checked instead (DEC-7). A change that can fail a build that- passes today, including a stricter rule for an existing finding, MAY ship- only in a minor release that names it.+ such as a prop type it cannot read, does not fail `--strict`. `--strict` also+ fails on two exact doc faults the `docs` check finds in prose (DEC-8): a+ copied passage, where two topics repeat 10 or more words word for word (a+ run of mostly function words, or one that three or more topics share, is not+ a copy), and fluff, a listed padding phrase or a topic whose share of content+ words is under the published floor. Its exit codes and JSON shape are a compatibility+ contract for the builds that run it, from the first stable release that+ ships `integration check`: from then on, a new check, or a new failure code,+ MAY join it only in a minor release that names the addition, and a change+ that can fail a build that passes, including a stricter rule for an existing+ finding, MAY ship only in a minor release that names it. Before that+ release, its checks and failure codes MAY change in any release. A name a+ patch release adds to Core or the CLI (a component, template, or topic) MAY+ raise a conflict with a package's own name. Each `doctor integration`+ subcommand MUST keep its exit codes, and its JSON MAY change only by+ additions. Because builds fail on its findings, it MUST NOT report a finding+ the package's code does not contradict, other than the doc faults of DEC-8:+ a check that cannot judge an item lists it as not checked instead (DEC-7).- **INV9 — A command that cannot support `--json` is rejected before any sideeffect**, not part-way through the work.- **INV10 — Every write is confined.** Output paths pass `assertWithin`, which@@ -589,9 +596,29 @@ Every integration runs `integration check --strict` in its build (DEC-6), so afalse finding fails a package for a fault it does not have, and its only wayout, dropping `--strict`, also drops the check for every real fault. A checkthat cannot tell whether the code contradicts a doc lists the item as not-checked, which `--strict` does not fail.+checked, which `--strict` does not fail. The one exception is the doc-quality+findings of DEC-8.Rejected: reporting a doubtful item as a warning (`--strict` fails it).+### DEC-8 — The strict check fails on copied passages and fluff in docs++**Decider:** `josephfarina`, `2026-10-20`++People and agents read integration docs on a budget. A fact written in two+topics goes stale in one of them at the next edit, and padding costs every+reader. So these doc-quality findings fail `--strict` by owner decision, as+the one exception to DEC-7. A copied passage (a run of identical words, after+the filters for function-word runs and for boilerplate that three or more+topics share) and a listed padding phrase (outside code and quotes) are exact+matches. The density floor is a threshold, not a contradiction. The phrase+list and the floor are published in the check's docs, and every finding+names the phrase, or the measured density and the floor, so its fix is+mechanical. Each is a warning, so `integration check --strict` fails on it and+an agent that runs the build fixes it, while `doctor integration docs` keeps+exit 0. `integration check` first ships with these rules, so no build that+passed before can newly fail.+Rejected: listing them as information only, which an agent treats as optional.+## Verification| Invariant | Evidence | Failure signal |@@ -620,7 +647,7 @@ Rejected: reporting a doubtful item as a warning (`--strict` fails it).| INV32 | `test/cli-strict-guard.test.mjs` lists every command offering `--strict` and every command whose exit depends on warnings; `api/integration/check/check.test.mjs` compares a strict run with the default run | A second command offers `--strict`, a command exits 1 on a warning alone without `--strict`, or a strict run reports a finding the default run does not or outside the command's issue format. || INV33 | `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/type-text.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-prop-docs.test.mjs` | A removed or renamed prop or a changed union passes unreported, a missing compiler reads as a pass, or a table that leaves out `ref`, `key`, `xstyle`, `className`, `style`, `data-testid`, or an `@internal` prop draws a warning. || INV34 | `foundation/discovery/doc-types.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-doc-types.test.mjs` | An unknown, missing, or mistyped field passes unreported, or a missing compiler reads as a pass. |-| INV35 | `api/integration/check/check.test.mjs`, `clients/cli/commands/integration-check.test.mjs`, `test/integration-check-failures.test.mjs`, `api/search/search.integration-check.test.mjs`, `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/type-match.test.mjs`, `foundation/discovery/doc-types.test.mjs` | The default exit differs from a check's own, a warning or a skipped comparison passes `--strict`, text and JSON exit differently, a new failing finding is added without the list changing, a search for ci does not find the command first, or a finding is reported on a doc the code does not contradict (for a type, one TypeScript accepts). |+| INV35 | `api/integration/check/check.test.mjs`, `clients/cli/commands/integration-check.test.mjs`, `test/integration-check-failures.test.mjs`, `api/search/search.integration-check.test.mjs`, `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/type-match.test.mjs`, `foundation/discovery/doc-types.test.mjs`, `api/integration/authoring-checks.test.mjs` | The default exit differs from a check's own, a warning or a skipped comparison passes `--strict`, text and JSON exit differently, a new failing finding is added without the list changing, a search for ci does not find the command first, a finding is reported on a doc the code does not contradict (for a type, one TypeScript accepts), or a copied passage or a fluff finding passes `--strict`, or a function-word run or shared boilerplate is reported as a copy. |## Open questions