Revised submission flow: open issue + draft PR together, with topic-hierarchy location

[stevevanhooser]

Context

Tracking issue: #28. This issue revises Step 5 ("Issue submission from the editor") and Step 6 ("Automated PR from approved submissions") of that plan.

The original Step 5/6 flow was:

1. Submitter clicks "Submit for review" in the editor → web app POSTs a new issue containing the JSON schema in a fenced ```json block.
2. A maintainer applies an approved label (or comments /approve) → a GitHub Action parses the issue body, writes the JSON to schemas/V_delta/<topic>/<class_name>.json, opens a PR, and links the issue.

Proposal

When the submitter clicks "Submit for review", the web app opens both an issue and a draft PR at the same time, so a reviewer can start working against a real diff immediately instead of waiting for maintainer triage.

Submission flow

1. User completes the form in the editor (Step 3 deliverable).
2. In the form, the user picks a topic from schemas/V_delta/topics.json as the proposed location in the hierarchy (with an "I'm not sure / propose a new topic" escape hatch that flags the submission for reviewer attention). The chosen topic + class_name determine the target path: schemas/V_delta/<topic>/<class_name>.json.
3. User clicks "Submit for review". The web app:
   • validates the JSON against the V_delta meta-schema (already done client-side in Step 3),
   • creates a branch submissions/<class_name> in this repo via the GitHub App,
   • commits the JSON file at the proposed path on that branch,
   • opens a draft PR from that branch to main with a schema-submission label and a needs-triage label,
   • opens a tracking issue with the rendered human-readable summary, links to the PR, and adds the same labels,
   • cross-links the two (issue body references the PR; PR body references the issue with Tracking: #<issue>).
4. After submission, the editor shows both the issue URL and the PR URL.

Why both an issue and a PR?

• PR: reviewers can see a real diff, CI runs, inline review comments work from day one, and reviewers can push commits to refine the submission before merge.
• Issue: the issue is the discussion thread for whether the schema should exist at all (concept, naming, topic placement). The PR is for how it's written. The issue closes when the PR merges (or is rejected).

Draft vs. ready

The PR is opened as draft so it does not look "ready to merge" to casual readers. A maintainer marks it ready-for-review once the submission has passed triage (or the submitter does, once they've addressed initial reviewer feedback).

Topic-hierarchy selection

• The form includes a topic picker populated from schemas/V_delta/topics.json (the same tree the viewer browses).
• The picker should support search/filter (the tree is large).
• "Propose a new topic" is allowed but adds a topic-proposal label, since adding a top-level topic is a bigger decision than adding one schema.
• The topic + class_name together determine the file path that the auto-PR writes.

Superclass selection

Already covered by Step 3's planned "superclass picker that lists existing V_delta class_names". The submission flow just passes whatever the form produced through to the PR; no extra logic needed beyond what Step 3 builds.

GitHub App permission changes

The original plan only needed issues: write. This revision requires:

• contents: write — to push the schema file to a submissions/<class_name> branch.
• pull-requests: write — to open the draft PR.
• issues: write — to open the tracking issue.

In-repo branches (rather than fork-based) keep the App's permissions self-contained and avoid asking submitters to authorize a fork.

Branch hygiene

• Branch name: submissions/<class_name> (one branch per submitted schema).
• If a branch with that name already exists, append a numeric suffix.
• Closed/rejected PRs: the branch is deleted by the same GitHub Action that processes the rejection label.

Open questions

• Existing-schema edits (Step 7): same flow, but the branch name would be edits/<class_name> and the action updates the file in place. Probably worth handling in this same submission infrastructure rather than as a follow-up.
• Abuse / spam: anyone with a GitHub account who installs the App on their account can submit. We may want a rate limit (e.g. N submissions per user per day) enforced by the Action. Not blocking for v1 since the needs-triage label gives maintainers a chokepoint.
• CI cost: every submission triggers the test suite. Acceptable for now given the submission rate we expect.

Supersedes

Replaces Step 5 and Step 6 as described in #28. Step 7 (edit-existing-schema) should be re-checked against this flow once it's implemented but the changes there should be small.

Implementation order (unchanged)

This proposal does not change the order of work. Step 3 (form + validation + Download JSON, no GitHub interaction) and Step 4 (device-flow login) still come first. This flow lands as a single Step 5+6 PR built on top of those two.