[josephfarina]

Exact decision needed

Who decides where a gap report goes when loaded integrations name their own issuesUrl, and how that choice reaches the CLI. Today a report always goes to the configured handlers (or, with none, the owning package's issuesUrl), so an integration's own tracker is unreachable whenever a handler is loaded.

Existing authority searched

• architecture:cli-surface (current, owner josephfarina) holds command contracts such as INV32–INV35 with DEC-4–DEC-8. This PR adds INV36, DEC-9, a change-coupling line, and a verification row.
• spec:AST-031 (draft, owners josephfarina and cixzhang) owns handler composition and the zero-handler fallback (FR8). Its draft FR13/DEC-4 (an automatic copy to the target integration's issuesUrl) is replaced: FR13 now says a destination named with --to replaces the handlers and the fallback for that report, and points to INV36. FR8, FR12, the fallback rule and the issuesUrl-metadata rule go back to their earlier wording. AST-031 stays a draft; the binding rule lives in the current record, as INV33–INV35 did.
• Open PRs touching these files: spec(cli-surface): INV30, how a host's package set serves the CLI #7412, spec(AST-081): global mode, so the CLI answers in any folder and a project's own release answers inside it #7601 (cli-surface), Spec: generate the visual-prop contract from TypeScript #6091, feat(DateInput): add exact theme-aware picker adaptations #6133 (AST-031). No shared invariant or decision number.

Decision

• INV36: astryx gap-report keeps the default route. --to <package> sends the report only to that loaded integration's issuesUrl (GitHub only with --confirm-public, otherwise routed_only). A --to naming no destination fails with ERR_UNKNOWN_PACKAGE before anything is sent and lists the choices. When at least one destination exists, --list-categories and the receipt of a run without --to list every destination, in text and JSON, and tell the agent to ask the person. Docs and agent guidance say the same: ask the person, never pick a package yourself, and leave out --to when the person does not choose.
• DEC-9: the person chooses; the CLI lists and the agent asks.

Rejected alternatives

• Copying every report to the integration's own issuesUrl automatically: reports land in places nobody picked.
• Letting the agent pick the destination.

Claim scope and non-goals

• Covers astryx gap-report and gapReport() only. Handler composition is unchanged.

Evidence and implementation relationship

The code PR #7724 implements INV36 with tests that fail on current main.

Writing rubric results

• R1 narration: one found, "as before" at the end of DEC-9; removed. None left.
• R2 research in the record: none.
• R3 evidence naming a change: none; the INV36 and FR13 verification rows name tests and states.
• R4 rejected alternatives over one line or outside a decision: two, one line inside DEC-9.
• R5 pull request or issue references remaining: none added.
• R6 ruled open questions still listing options: none.

Scope

• This PR contains specification records only.
• It records observable behavior and preserves equivalent internal implementations.
• Any named internal mechanism is intentionally public, names its dependent caller/system, and explains why an equivalent implementation would not satisfy the contract.
• Verification states the evidence layer and failure signal without prescribing CI job/workflow topology.
• It records one intentional durable decision, not a rescue for a separable tagalong.
• The canonical knowledge owner, affected current claims, and overlapping open work are named; any ownership collision is resolved or called out for human decision.
• Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.
• Public text and artifacts contain no internal Meta context.

Validation

• pnpm check:knowledge (inside pnpm check:repo): passes.
• Prettier: AST-031 passes; cli-surface.md is not Prettier-clean on main, so it was edited by hand to avoid re-padding the whole table.
• git diff --check: clean.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Oct 20, 2026 6:17pm UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
🔄 In progress (for maintainers only)	Oct 20, 2026, 6:11 PM UTC

[josephfarina]

/approve-spec ad360a6

[github-actions]

PR Analysis Report

Previews ready: Storybook and Sandbox were built with this PR's docsite. CI evidence will be added when available.

View Storybook for this PR · View Sandbox for this PR