An open source design system that's fully customizable and agent ready
TypeScript
spec(cli-surface, AST-031): the person filing a gap report chooses where it goes (#7749)
Joey3fb02c30e4d7
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.mdindex 57adbea187..11715d0b2c 100644--- a/docs/architecture/cli-surface.md+++ b/docs/architecture/cli-surface.md@@ -191,6 +191,23 @@ and remains available through explicit Core package selection.additions. Because builds fail on its findings, it MUST NOT report a findingthe 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).+- **INV36 — The person filing a gap report chooses where it goes.**+ `astryx gap-report` MUST send a report to the configured report handlers, or+ with none to the owning package's `issuesUrl` (`spec:AST-031` FR8), unless+ the caller names a destination with `--to <package>`. A destination is a+ loaded integration whose manifest sets `issuesUrl`. With `--to`, the report+ goes only to that `issuesUrl`, the way the zero-handler fallback sends it: a+ GitHub issues URL is filed only with `--confirm-public` and reports+ `consent_required` without it, and any other URL comes back as+ `routed_only`. A `--to` that names no destination MUST fail with+ `ERR_UNKNOWN_PACKAGE` before anything is sent, listing the destinations it+ accepts. While at least one destination exists, the categories listing and+ the receipt of a run without `--to` MUST list the default and every+ destination, in text and JSON, and MUST tell the agent to ask the person+ where to file and to pass the person's choice with `--to`. The command's+ docs and agent guidance MUST say the same: an agent asks the person, never+ picks a package destination on its own, and leaves out `--to` when the person+ does not choose (DEC-9).- **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@@ -458,7 +475,9 @@ updated in the same pull request when it moves an invariant:- changing local, configured, or autolinked integration precedence;- changing an integration item descriptor, the theme directory boundary, or the consumer copy contract;- changing which files hold the agent-docs block, how init finds the project- root, where it refuses to write agent docs, or where it removes them (INV31).+ root, where it refuses to write agent docs, or where it removes them (INV31);+- adding a kind of gap-report destination, or changing who chooses one+ (INV36).`pnpm check:cli-structure` enforces the layout. The contract tests listed in`verified_by` enforce the envelope, the exit codes, the error codes, and the@@ -619,6 +638,19 @@ exit 0. `integration check` first ships with these rules, so no build thatpassed before can newly fail.Rejected: listing them as information only, which an agent treats as optional.+### DEC-9 — The person chooses where a gap report goes++**Decider:** `josephfarina`, `2026-10-20`++Report handlers usually feed one shared place, while an integration names its+own tracker in `issuesUrl`. Which place should get a report is a judgment about+the gap, so the person decides: the CLI lists the places, the agent asks, and+`--to` carries the answer. Without a choice the report goes to the shared+default.+Rejected: copying every report to the integration's own `issuesUrl`+automatically (reports land in places nobody picked); letting the agent pick+the destination.+## Verification| Invariant | Evidence | Failure signal |@@ -648,6 +680,7 @@ Rejected: listing them as information only, which an agent treats as optional.| 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`, `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. |+| INV36 | `api/gap-report/gap-report.test.mjs`, `clients/cli/commands/gap-report.test.mjs` | A run without `--to` reaches an `issuesUrl` the handlers did not choose, `--to` runs a handler or files on GitHub without `--confirm-public`, an unknown `--to` sends anything, or the destinations list or its line telling the agent to ask the person is missing while a destination exists. |## Open questionsdiff --git a/docs/specs/AST-031/spec.md b/docs/specs/AST-031/spec.mdindex f74244d34c..881db800c5 100644--- a/docs/specs/AST-031/spec.md+++ b/docs/specs/AST-031/spec.md@@ -111,17 +111,15 @@ confirmation.A built-in fallback (e.g. opening a GitHub issue via `issuesUrl`) activates**only** when the effective handler set is empty after deduplication. The-presence of any configured handler — project or integration — suppresses that-fallback. A feature may still route to the target package's own destination-beside its handlers; for gap reports, FR13 defines that route.+presence of any configured handler — project or integration — suppresses the+fallback entirely.#### issuesUrl is target metadata`issuesUrl` on an integration manifest or project config describes thedestination for human-readable issue links. It is metadata about the targetpackage, not a handler implementation. Handlers use it as context; the CLI-uses it for fallback routing and, for gap reports, for the target route-(FR13).+uses it for fallback routing.#### Mutation-sensitive tests@@ -182,8 +180,7 @@ fail-closed guard MUST break a test.(zero handlers after deduplication), and the target has a GitHub `issuesUrl`,the CLI offers to file via `gh issue create`. This fallback is consent-gated(`public` audience). Any other `issuesUrl` scheme produces a `routed_only`- receipt. This zero-handler fallback is suppressed when at least one handler- exists; FR13 defines the route that still reaches the target package.+ receipt. The fallback is suppressed entirely when at least one handler exists.- **FR9 — Project config field.** `astryx.config` gains a `gapReport` fieldaccepting a `GapReportHandler`. This is the project-level handler and runs@@ -200,24 +197,14 @@ fail-closed guard MUST break a test.handlers still run even when a gated sibling is blocked.- **FR12 — Aggregate response.** The command's response includes a `deliveries`- array with one entry per effective handler, fallback, or FR13 target route.- Each delivery records `handlerType`, `handler`, `audience`, `status`, `url`,- and `message`. The response shape is the same in `--json` and human output- modes.--- **FR13 — The package a report is about also receives it.** When the- effective handler set is not empty and the target is an integration package- whose own manifest sets `issuesUrl`, the CLI also routes the report to that- `issuesUrl` after the handlers, the same way the FR8 fallback does: a GitHub- issues URL is filed with `gh issue create` only with caller consent- (`consent_required` otherwise), and any other URL produces a `routed_only`- delivery naming it. The route is one more delivery with- `handlerType: 'fallback'`. It does not run when the target is Core, whose- reports the handlers already receive; when the target package's own handler- is in the effective set; or when a handler delivery's `url` lies inside that- `issuesUrl` (same origin, and its path starts with the issues URL's path). So- one place never receives the same report twice. The route's outcome never- changes a handler's delivery.+ array with one entry per effective handler or fallback. Each delivery records+ `handlerType`, `handler`, `audience`, `status`, `url`, and `message`. The+ response shape is the same in `--json` and human output modes.++- **FR13 — A destination the caller names.** When the caller names a+ destination with `--to`, that destination replaces the handlers and the FR8+ fallback for that report. `architecture:cli-surface` INV36 governs the option+ and who chooses the destination.#### Platform support@@ -241,27 +228,23 @@ integration handler, and each handler returns its own receipt. Existing consumerwithout handlers keep the consent-gated `issuesUrl` fallback. No released config orintegration API requires migration because the single-writer shape has not shipped.-With handlers loaded, a report about an integration that sets its own-`issuesUrl` also reaches that `issuesUrl` (FR13). The delivery uses the-existing `fallback` delivery kinds, so the response shape gains no new values.----## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| -------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |-| FR1–FR3 | gap-report handler type and receipt contract tests | valid handler; missing audience; wrong status value; non-object return | an invalid handler shape or receipt is accepted silently |-| FR4 | handler isolation tests | handler writes stdout; handler calls process.exit; handler throws; handler exceeds 30 s | stdout corruption reaches the JSON envelope, or exit/throw stops later handlers |-| FR5 | no-opt-out assertion test | project sets `inheritDebug: false` in package.json; gap-report handlers still run | an opt-out mechanism suppresses a gap-report handler |-| FR6 | effective-set ordering and deduplication tests | project + two integrations; duplicate handle ref; project only; integrations only | wrong order, duplicate execution, or missing handler |-| FR7 | target selection tests | explicit package; unique owner; ambiguous owner requiring `--package`; no component match | handler count influences target, ambiguity is guessed, or an unknown component fails to default to Core |-| FR8 | fallback activation and suppression tests | zero handlers + GitHub issuesUrl; zero handlers + non-GitHub issuesUrl; one handler present | fallback fires with a handler present, or non-GitHub issuesUrl claims it filed |-| FR9–FR10 | config field and named-export loading tests | project config with gapReport; integration with named export; both present; neither present | config field ignored, named export ignored, or old CLI breaks on named export |-| FR11 | mixed-audience consent tests | all internal; all public with consent; all public without consent; mixed with partial consent | a public handler runs without consent, or an internal handler is blocked by consent |-| FR12 | aggregate response shape tests | all succeed; one fails; one times out; consent_required entries; empty set (fallback) | missing delivery entry, wrong source attribution, or response shape differs between --json and human |-| FR13 | target route tests | handler + integration target with GitHub issuesUrl, with and without consent; non-GitHub issuesUrl; Core target; the target's own handler; receipt url inside issuesUrl | the route is skipped for an integration target, sent twice to one place, sent for Core, or filed publicly without consent |-| General | mutation-sensitive composition tests (structuredClone) | handler mutates event fields; handler adds properties to event | mutation leaks to a subsequent handler |+| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |+| FR1–FR3 | gap-report handler type and receipt contract tests | valid handler; missing audience; wrong status value; non-object return | an invalid handler shape or receipt is accepted silently |+| FR4 | handler isolation tests | handler writes stdout; handler calls process.exit; handler throws; handler exceeds 30 s | stdout corruption reaches the JSON envelope, or exit/throw stops later handlers |+| FR5 | no-opt-out assertion test | project sets `inheritDebug: false` in package.json; gap-report handlers still run | an opt-out mechanism suppresses a gap-report handler |+| FR6 | effective-set ordering and deduplication tests | project + two integrations; duplicate handle ref; project only; integrations only | wrong order, duplicate execution, or missing handler |+| FR7 | target selection tests | explicit package; unique owner; ambiguous owner requiring `--package`; no component match | handler count influences target, ambiguity is guessed, or an unknown component fails to default to Core |+| FR8 | fallback activation and suppression tests | zero handlers + GitHub issuesUrl; zero handlers + non-GitHub issuesUrl; one handler present | fallback fires with a handler present, or non-GitHub issuesUrl claims it filed |+| FR9–FR10 | config field and named-export loading tests | project config with gapReport; integration with named export; both present; neither present | config field ignored, named export ignored, or old CLI breaks on named export |+| FR11 | mixed-audience consent tests | all internal; all public with consent; all public without consent; mixed with partial consent | a public handler runs without consent, or an internal handler is blocked by consent |+| FR12 | aggregate response shape tests | all succeed; one fails; one times out; consent_required entries; empty set (fallback) | missing delivery entry, wrong source attribution, or response shape differs between --json and human |+| FR13 | named destination tests | `--to` naming an integration with a GitHub issuesUrl, with and without consent; a non-GitHub issuesUrl; an unknown package | a handler runs with `--to`, or an unknown destination sends anything |+| General | mutation-sensitive composition tests (structuredClone) | handler mutates event fields; handler adds properties to event | mutation leaks to a subsequent handler |---@@ -310,21 +293,6 @@ Rejected: selecting the target by handler count or integration order; silentlychoosing one ambiguous owner; distributing target ownership to every package thatships a handler.-### DEC-4 — A report also reaches the package it is about--**Reference:** `spec:AST-031/DEC-4`-**Decider:** `josephfarina`, `2026-10-19`--Handlers often belong to a shared place that collects every report, while each-integration names its own tracker in `issuesUrl`. Sending only to the handlers-would leave an integration's own tracker without reports about its components-whenever any handler is loaded. The CLI therefore routes to the target integration's-own `issuesUrl` as well, with the same consent rule, and skips it when that-place already received the report.--Rejected: sending to every loaded integration's `issuesUrl`, which spreads one-report across unrelated trackers.-## Open questionsNone.