Merge origin/main into resolve-path-race

Resolve import path conflict: BaseApp moved from core/app/index.js
to core/app/entrypoints/index.js on main.

Author: ascorbic

.agents/skills/triage/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: triage
-description: Triage a bug report. Reproduces the bug, diagnoses the root cause, and attempts a fix. Use when asked to "triage issue #1234", "triage this bug", or similar.
+description: Triage a bug report. Reproduces the bug, diagnoses the root cause, verifies whether the behavior is intentional, and attempts a fix. Use when asked to "triage issue #1234", "triage this bug", or similar.
 ---
 
 # Triage
 
-Triage a bug report end-to-end: reproduce the bug, diagnose the root cause, and attempt a fix.
+Triage a bug report end-to-end: reproduce the bug, diagnose the root cause, verify whether the behavior is intentional, and attempt a fix.
 
 ## Input
 
@@ -35,7 +35,16 @@ After completing diagnosis, check your confidence:
 - If confidence is **low** — skip to Output.
 - If confidence is **medium** or **high** — continue to Step 3.
 
-## Step 3: Fix
+## Step 3: Verify
+
+Read and follow [verify.md](verify.md). Use a subagent for this step to isolate context.
+
+After completing verification, check the verdict:
+
+- If the verdict is **intended-behavior** — skip to Output. The issue is not a bug; do not attempt a fix.
+- If the verdict is **bug** or **unclear** — continue to Step 4.
+
+## Step 4: Fix
 
 Read and follow [fix.md](fix.md). Use a subagent for this step to isolate context.
 

.agents/skills/triage/comment.md

@@ -2,15 +2,17 @@
 
 Generate a GitHub issue comment from triage findings.
 
-**CRITICAL: You MUST always produce a GitHub comment as your final output, regardless of what input files are available. Even if `report.md` is missing or empty, you must still produce a comment. In that case, produce a minimal comment stating that automated triage could not be completed.**
+**CRITICAL: You MUST always read `report.md` and produce a GitHub comment as your final output, regardless of what input files are available. Even if `report.md` is missing or empty, you must still produce a comment. In that case, produce a minimal comment stating that automated triage could not be completed.**
 
 ## Prerequisites
 
 These variables are referenced throughout this skill. They may be passed as args by an orchestrator, or inferred from the conversation when run standalone.
 
 - **`triageDir`** — Directory containing the reproduction project (e.g. `triage/issue-123`). If not passed as an arg, infer from previous conversation.
-- **`report.md`** — File in `triageDir` that MAY exist. Contains the full context from all previous skills (reproduction, diagnosis, fix).
+- **`issueDetails`** - The GitHub API issue details payload. This must be provided explicitly by the user or available from prior conversation context / tool calls. If this data isn't available, you may run `gh issue view ${issue_number}` to load the missing issue details directly from GitHub.
+- **`report.md`** — File in `triageDir` that MAY exist. Contains the full context from all previous skills (reproduction, diagnosis, fix). Contains everything that you need to know to generate your comment successfully.
 - **`branchName`** — The branch name where a fix was pushed. If not passed as an arg, infer from previous conversation.
+- **`priorityLabels`** — An array of `{ name, description }` objects representing the available priority labels for the repository. Used to select a priority in the comment.
 
 ## Overview
 
@@ -27,22 +29,28 @@ If `report.md` is missing or empty, generate a minimal comment (see "Fallback" s
 
 Generate and return a GitHub comment following the template below.
 
-### Special Cases
+### "Fix" Instructions
 
-- **If the user is on a different major version than the current monorepo, and the issue could not be reproduced in the current monorepo:** In the "Fix" section of your comment, the best guidance you can provide is to suggest that the user upgrade to that newer major version to fix their issue, even if that newer major version is a beta release. Link to the relevant upgrade guide:
-  - v6: https://v6.docs.astro.build/en/guides/upgrade-to/v6/
-  - v5: https://docs.astro.build/en/guides/upgrade-to/v5/
+The **Fix** line in the template has three possible forms. Choose the one that matches the triage outcome:
+
+1. **You created a fix:** Use `I was able to fix this issue.` and include the suggested fix link.
+2. **The issue is already fixed on main** (e.g. the user is on an older major version and the bug doesn't reproduce on current main): Use `This issue has already been fixed.` and tell the user how to get the fix (e.g. upgrade). Link the relevant upgrade guide if applicable: [v6](https://v6.docs.astro.build/en/guides/upgrade-to/v6/), [v5](https://docs.astro.build/en/guides/upgrade-to/v5/).
+3. **You could not find or create a fix:** Use `I was unable to find a fix for this issue.` and give guidance or a best guess at where the fix might be.
+
+### "Priority" Instructions
+
+The **Priority** line communicates the severity of this issue to maintainers. Its goal is to answer the question: **"How bad is it?"**
+
+Select exactly ONE priority label from the `priorityLabels` arg. Use the label descriptions to guide your decision, combined with the triage report's root cause and impact analysis. Render the chosen label name in square brackets, in bold, formatted with the `- ` prefix removed (Example: `**[P2: Has Workaround].**). Then, follow it with 1-2 sentences explaining **why** you chose that priority. Answer: "who is likely to be affected and under what conditions?". If you are unsure, use your best judgment based on the label descriptions and the triage findings.
 
 ### Template
 
 ```markdown
-**[I was able to reproduce this issue. / I was unable to reproduce this issue.]** [1-2 sentences describing the result and key observations.]
-
-**Fix:** **[I was able to fix this issue. / I was unable to fix this issue]** [1-2 sentences describing the solution and key observations. Even if no fix was created, you can still use this space to give guidance or "a best guess" at where the fix might be.] [If `branchName` arg is non-null, include this link: [View Fix](https://github.com/withastro/astro/compare/{branchName}?expand=1)]
+**[I was able to reproduce this issue. / I was unable to reproduce this issue.]** [2-3 sentences describing the root cause, result, and key observations.]
 
-**Cause:** [Single sentence explaining the root cause - or just the word "Unknown" if not determined.]
+**Fix:** **[See "Fix" Instructions above.]** [1-2 sentences describing the solution, where/when it was already fixed, or guidance on where a fix might be.] [If `branchName` is non-null: [View Suggested Fix](https://github.com/withastro/astro/compare/{branchName}?expand=1)]
 
-**Impact:** [Single sentence describing who is affected and how - or just the word "Unknown" if not determined.]
+**Priority:** **[See "Priority" Instructions above.]** [1-2 sentences explaining why this priority was chosen, who is likely to be affected, and under what conditions (this section should answer the question: "how bad is it?")]
 
 <details>
 <summary><em>Full Triage Report</em></summary>
@@ -54,11 +62,14 @@ Generate and return a GitHub comment following the template below.
 _This report was made by an LLM. Mistakes happen, check important info._
 ```
 
-## Optional Follow-up Task
+## Result
+
+You MUST RETURN the generated comment text so that the user can review and post it themselves.
 
-You MAY SUGGEST to the user, as a potential follow-up step, to post the issue to GitHub directly. However you CANNOT DO THIS STEP unless the user explicitly asks.
+You MAY SUGGEST to the user that you (or they) could post the comment to the GitHub issue. **Do not post the comment yourself** — this should only be a suggestion. It would be a horrifying abuse of trust to the user if you posted to GitHub on their behalf without their explicit permission.
 
 ```bash
+# Example Only:
 gh issue comment <issue_number> --body <comment>
 gh issue comment <issue_number> --body-file <path-to-file>
 ```

.agents/skills/triage/diagnose.md

@@ -2,14 +2,16 @@
 
 Find the root cause of a reproduced bug in the Astro source code.
 
-**CRITICAL: You MUST always append to `report.md` before finishing, regardless of outcome. Even if you cannot identify the root cause, hit errors, or the investigation is inconclusive — always update `report.md` with your findings. The orchestrator and downstream skills depend on this file to determine what happened.**
+**CRITICAL: You MUST always read `report.md` and append to `report.md` before finishing, regardless of outcome. Even if you cannot identify the root cause, hit errors, or the investigation is inconclusive — always update `report.md` with your findings. The orchestrator and downstream skills depend on this file to determine what happened.**
 
 ## Prerequisites
 
 These variables are referenced throughout this skill. They may be passed as args by an orchestrator, or inferred from the conversation when run standalone.
 
 - **`triageDir`** — Directory containing the reproduction project (e.g. `triage/issue-123`). If not passed as an arg, infer from previous conversation.
+- **`issueDetails`** - The GitHub API issue details payload. This must be provided explicitly by the user or available from prior conversation context / tool calls. If this data isn't available, you may run `gh issue view ${issue_number}` to load the missing issue details directly from GitHub.
 - **`report.md`** — File in `triageDir` that MAY exist. Contains the full context from all previous skills.
+- **Astro Compiler source** — The `withastro/compiler` repo MAY be cloned at `.compiler/` (inside the repo root, gitignored). If it exists, treat it as in-scope for diagnosis. Some bugs originate in the compiler rather than in `packages/` — if stack traces or investigation point to compiler behavior (e.g. HTML parsing, `.astro` file transformation), check `.compiler/` for relevant source code.
 
 ## Overview
 
@@ -21,11 +23,7 @@ These variables are referenced throughout this skill. They may be passed as args
 
 ## Step 1: Review the Reproduction
 
-Read `report.md` from the `triageDir` directory to understand:
-
-- The exact error message and stack trace
-- Which command triggers the issue (build/dev/preview)
-- What user code is involved
+Start by reading `report.md` from the `triageDir` directory.
 
 **Skip if not reproduced:** If `report.md` shows the bug was NOT reproduced or was skipped (look for "could not reproduce", "SKIP REASON", "skipped: true"), append "DIAGNOSIS SKIPPED: No reproduction" to `report.md` and return `confidence: null`.
 

.agents/skills/triage/fix.md

@@ -2,24 +2,28 @@
 
 Develop and verify a fix for a diagnosed Astro bug.
 
-**CRITICAL: You MUST always append to `report.md` before finishing, regardless of outcome. Even if the fix attempt fails, you encounter errors, or you cannot resolve the bug — always update `report.md` with your findings. The orchestrator and downstream skills depend on this file to determine what happened.**
+**CRITICAL: You MUST always read `report.md` and append to `report.md` before finishing, regardless of outcome. Even if the fix attempt fails, you encounter errors, or you cannot resolve the bug — always update `report.md` with your findings. The orchestrator and downstream skills depend on this file to determine what happened.**
 
 ## Prerequisites
 
 These variables are referenced throughout this skill. They may be passed as args by an orchestrator, or inferred from the conversation when run standalone.
 
 - **`triageDir`** — Directory containing the reproduction project (e.g. `triage/issue-123`). If not passed as an arg, infer from previous conversation.
+- **`issueDetails`** - The GitHub API issue details payload. This must be provided explicitly by the user or available from prior conversation context / tool calls. If this data isn't available, you may run `gh issue view ${issue_number}` to load the missing issue details directly from GitHub.
 - **`report.md`** — File in `triageDir` that MAY exist. Contains the full context from all previous skills.
+- **Astro Compiler source** — The `withastro/compiler` repo MAY be cloned at `.compiler/` (inside the repo root, gitignored). If it exists and the root cause is in the compiler, investigate and propose fixes there. This clone is **reference only** — it is not wired into the monorepo's dependencies, so compiler changes cannot be tested end-to-end here. Document proposed compiler changes and diff in `report.md` instead.
 
 ## Overview
 
 1. Review the diagnosis from `report.md`
-2. Implement a minimal fix in `packages/`
-3. Rebuild the affected package(s)
-4. Verify the fix resolves the reproduction
-5. Ensure no regressions
-6. Generate git diff
-7. Append fix details to `report.md`
+2. Verify fix feasibility (browser/runtime compatibility)
+3. Implement a minimal fix in `packages/`
+4. Rebuild the affected package(s)
+5. Verify the fix resolves the reproduction
+6. Ensure no regressions
+7. Generate git diff
+8. Append fix details to `report.md`
+9. Clean up the working directory
 
 ## Step 1: Review the Diagnosis
 
@@ -33,7 +37,14 @@ Read `report.md` from the `triageDir` directory to understand:
 
 **Note:** The repo may be messy from previous steps. Check `git status` and either work from the current state or `git reset --hard` to start clean.
 
-## Step 2: Implement the Fix
+## Step 2: Verify Fix Feasibility
+
+Consider your potential fixes and verify that any modern features you plan to use are supported:
+
+- **Node.js:** When writing code for the runtime (server, build logic, integrations, etc.), target Node.js version `>=22.12.0`.
+- **Browsers:** If your fix relies on browser support for any web platform feature, check the browser compatibility table on MDN to confirm it is supported across our browser targets. Do not treat specification compliance as proof of browser support. If the feature lacks sufficient support, choose a different approach.
+
+## Step 3: Implement the Fix
 
 Make changes in `packages/` source files. Follow these principles:
 
@@ -69,7 +80,7 @@ export function renderComponent(component: AstroComponent, props: Props) {
 }
 ```
 
-## Step 3: Rebuild the Package
+## Step 4: Rebuild the Package
 
 After making changes, rebuild the affected package:
 
@@ -79,15 +90,15 @@ pnpm -C packages/astro build    # or packages/integrations/<name>
 
 Watch for build errors — fix any TypeScript issues before proceeding.
 
-## Step 4: Verify the Fix
+## Step 5: Verify the Fix
 
 Re-run the reproduction, often using `pnpm run build`/`astro build` or `pnpm run dev`/`astro dev`.
 
-## Step 5: Check for Regressions
+## Step 6: Check for Regressions
 
 Test that you didn't break anything new, and that normal cases still work. If you find regressions, refine the fix to handle all cases.
 
-## Step 6: Generate Git Diff
+## Step 7: Generate Git Diff
 
 From the repository root, generate the diff:
 
@@ -97,7 +108,7 @@ git diff packages/
 
 This captures all your changes for the report.
 
-## Step 7: Write Output
+## Step 8: Write Output
 
 Append your fix details to the existing `report.md` (written by reproduce and diagnose skills).
 
@@ -112,7 +123,7 @@ The report must include all information needed for a final GitHub comment to be
 - Any alternative approaches considered and their tradeoffs
 - If the fix failed: what was tried and why it didn't work
 
-## Step 8: Clean Up the Working Directory
+## Step 9: Clean Up the Working Directory
 
 1. Run `git status` and review all changed files
 2. Revert any changes that are NOT part of the fix: