feat(framework): ticket format specifies .plan.md (#791)

.changeset/feat-791-ticket-plan-format.md

@@ -0,0 +1,5 @@
+---
+'@gemstack/framework': minor
+---
+
+Ticket format: specify `tickets/<DATE>_<SLUG>.plan.md`, the detailed plan that sits beside a ticket and its spike. An agent writing one now has the shape (TLDR, Plan, optional Hard problems and Variability) and, for a low-rated aspect with alternatives, presents them with showChoices() and AWAIT instead of picking silently.

packages/framework/prompts/ticketing_format.md

@@ -52,3 +52,44 @@ Typical spike content:
 - Estimated effort (for each ways to implement it):
   - Human intervention effort: trivial/low/medium/high/very-high
   - Token consumption: time estimate (minutes, hours, or days)
+
+## tickets/<DATE>_<SLUG>.plan.md
+
+For an existing ticket (e.g. `tickets/2042-01-01_some-ticket.md`), a detailed plan can be created (`tickets/2042-01-01_some-ticket.plan.md`).
+
+Body:
+```md
+# [Plan] Ticket title
+
+## TLDR
+
+...
+
+## Plan
+
+...
+
+## Hard problems [optional]
+
+...
+
+## Variability [optional]
+
+...
+
+[optional: more info (any heading and format you want)]
+```
+
+Typical plan content:
+- Concrete and detailed plan on how to implement the ticket, for example:
+  - Exhaustive list of all aspects (including edge cases)
+  - Thorough analysis
+  - Overview of code changes
+  - ...
+- Hard problems
+  - Exhaustive list of all aspects with low confidence regarding how to solve them (the hard problems), with explanation why
+- Variability
+  - List all aspects that need to be implemented
+  - Give a rating to each aspect (from 0 to 10) following this criteria: is there an obviously optimal way to implement it (10), or is it highly unclear whether it can be implemented in a better way (0)?
+  - Explore and suggest alternatives for aspects with a low rating
+  - For each aspect that has alternatives: list all alternatives sorted in a sensible order, then ask the user to pick one with showChoices() and AWAIT (one question per aspect, recommending the alternative you'd pick)

packages/framework/src/tickets.ts

@@ -12,7 +12,7 @@ export const TICKETS_DIR = 'tickets'
 
 /**
  * The ticket-format spec (#684): the static reference an agent opens to learn the
- * `tickets/<DATE>_<SLUG>.md` (and `.spike.md`) file shape. Per Rom's #674 call it ships
+ * `tickets/<DATE>_<SLUG>.md` (and `.spike.md` / `.plan.md`) file shape. Per the #674 call it ships
  * *inside the installed package* rather than being materialized into the repo, so a future
  * breaking change to the format rides with the package version instead of going stale in a
  * committed file. The package ships `prompts/ticketing_format.md` (see the `files` allowlist),