Skip to content

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.md
index 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 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).
+- **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 side
effect**, 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 that
passed 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 questions
diff --git a/docs/specs/AST-031/spec.md b/docs/specs/AST-031/spec.md
index 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 the
destination for human-readable issue links. It is metadata about the target
package, 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` field
accepting 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 consumer
without handlers keep the consent-gated `issuesUrl` fallback. No released config or
integration 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; silently
choosing one ambiguous owner; distributing target ownership to every package that
ships 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 questions
None.