@hybridlabor-api/aos 4.13.2 → 4.14.1

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/feature/plan.mdx

@@ -0,0 +1,145 @@
+---
+title: Trailmark - Saved Routes
+status: draft
+needs-api: foundations
+needs-screens: api
+needs-sync: api
+needs-launch: screens, sync
+---
+
+# Trailmark: Saved Routes
+
+<Callout tone="note" title="How to use this template">
+
+Replace the Trailmark example with your feature: rewrite the Goal and success list, swap the Decision for your real fork in the road, edit the screens in canvas.mdx (keep ids in sync with the transitions), and replace the build map sections and file paths. Delete sections you do not need. All names here are invented.
+
+</Callout>
+
+## Goal
+
+Trailmark is a fictional hiking app. Saved Routes lets a hiker bookmark a route from the map, find it again offline and sync it across devices. The feature ships to the beta group in four weeks.
+
+- A hiker saves a route in two taps from the map.
+- Saved routes open without a network connection.
+- A route saved on the phone shows up on the tablet within a minute.
+
+## Storyboard
+
+Four screens in canvas.mdx cover the happy path: map, save sheet, saved list, route detail.
+
+## Decision
+
+<Decision title="Where do saved routes live?" question="Which store is the source of truth for a saved route?" options={[
+  { id: "local-first", label: "Local database with background sync", detail: "Works offline by design, needs a conflict rule.", recommended: true },
+  { id: "server", label: "Server only, cached reads", detail: "Simple model, but the list is empty offline until cached." },
+  { id: "file", label: "Exported GPX files", detail: "Portable, but no sync and no list ordering." },
+]}>
+
+Hikers lose signal on exactly the trails they want to follow. A local database makes offline the normal case, and last-edit-wins per route is enough for one person using two devices.
+
+</Decision>
+
+## Flow
+
+<Mermaid label="Save and sync" source={"sequenceDiagram\n  participant H as Hiker\n  participant A as App\n  participant L as Local DB\n  participant S as Sync API\n  H->>A: Tap Save on a route\n  A->>L: Insert route with revision 1\n  A-->>H: Show Saved toast\n  A->>S: Push pending changes\n  S-->>A: Accepted, server revision\n  A->>L: Mark route synced"} />
+
+## Acceptance {#acceptance}
+
+<Checklist title="Done when" items={[
+  { label: "Save from the map takes two taps or fewer" },
+  { label: "Saved list opens in airplane mode" },
+  { label: "Removing a route on one device removes it on the other" },
+  { label: "A list of 500 routes scrolls without dropped frames" },
+  { label: "Screen reader announces Saved and Removed" },
+]} />
+
+## Build map
+
+### Foundations {#foundations}
+
+Schema and feature flag.
+
+<Checklist title="Foundations tasks" items={[
+  { label: "Feature flag saved_routes, off by default", checked: true },
+  { label: "Local table saved_routes with revision and deleted_at" },
+]} />
+
+<ImplementationMap files={[
+  { path: "app/db/migrations/012_saved_routes.sql", change: "added", note: "Table with revision and tombstone column" },
+  { path: "app/flags.ts", change: "modified", note: "Add saved_routes flag" },
+]} />
+
+### Sync API {#api}
+
+Push and pull endpoints with a revision check.
+
+<Checklist title="API tasks" items={[
+  { label: "POST /v1/saved-routes/push with revision check" },
+  { label: "GET /v1/saved-routes/pull?since=cursor" },
+  { label: "Tombstones kept for 30 days" },
+]} />
+
+<ImplementationMap files={[
+  { path: "server/routes/saved-routes.ts", change: "added", note: "Push and pull handlers" },
+  { path: "server/jobs/purge-tombstones.ts", change: "added", note: "Nightly cleanup after 30 days" },
+]} />
+
+### Screens {#screens}
+
+Save sheet, saved list and route detail.
+
+<Checklist title="Screen tasks" items={[
+  { label: "Save button and bottom sheet on the map" },
+  { label: "Saved list with sort and empty state" },
+  { label: "Route detail with remove action" },
+]} />
+
+<ImplementationMap files={[
+  { path: "app/screens/SaveSheet.tsx", change: "added", note: "Name, folder and Save button" },
+  { path: "app/screens/SavedList.tsx", change: "added", note: "Virtualised list and empty state" },
+  { path: "app/screens/RouteDetail.tsx", change: "added", note: "Map preview, stats, remove" },
+]} />
+
+### Sync client {#sync}
+
+Background push and pull with retry.
+
+<Checklist title="Sync tasks" items={[
+  { label: "Push pending rows on connectivity change" },
+  { label: "Pull on app start and every five minutes" },
+  { label: "Last edit wins, ties broken by device id" },
+]} />
+
+<ImplementationMap files={[
+  { path: "app/sync/saved-routes-sync.ts", change: "added", note: "Push, pull and conflict rule" },
+]} />
+
+### Launch {#launch}
+
+Beta rollout.
+
+<Checklist title="Launch tasks" items={[
+  { label: "Enable flag for the beta group" },
+  { label: "Watch sync error rate for three days" },
+]} />
+
+<AgentTrail />
+
+## Risks
+
+<Table title="Risks" columns={["Risk", "Likelihood", "Impact", "Mitigation"]} rows={[
+  ["Two devices edit the same route offline", "Medium", "Low", "Last edit wins, keep the older copy in a recently-deleted list"],
+  ["Large saved lists slow the map", "Low", "Medium", "Load the list lazily, never on map start"],
+  ["Tombstones grow without bound", "Low", "Low", "Nightly purge after 30 days"],
+]} />
+
+## Open questions
+
+<QuestionForm title="Open Questions" questions={[
+  { title: "Can routes be grouped in folders?", mode: "single", options: [
+    { label: "Not in the beta", recommended: true }, { label: "One level of folders" } ] },
+  { title: "Default sort of the saved list?", mode: "single", options: [
+    { label: "Recently saved", recommended: true }, { label: "Distance from here" }, { label: "Alphabetical" } ] },
+  { title: "Which extras do we want in the beta?", mode: "multi", options: [
+    { label: "Share a route link" }, { label: "Export as GPX" }, { label: "Notes on a saved route" } ] },
+]} />

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/feature/standard.md

@@ -0,0 +1,76 @@
+# Trailmark: Saved Routes
+
+> **How to use this template:** replace the Trailmark example with your feature. Rewrite the goal, the decision, the screens, the build order and the open questions. All names here are invented.
+
+**Status:** draft  **Target:** beta group in four weeks
+
+## 1. Goal
+
+Trailmark is a fictional hiking app. Saved Routes lets a hiker bookmark a route from the map, find it again offline and sync it across devices.
+
+- A hiker saves a route in two taps from the map.
+- Saved routes open without a network connection.
+- A route saved on the phone shows up on the tablet within a minute.
+
+## 2. Screens
+
+| # | Screen | Purpose | Next |
+|---|--------|---------|------|
+| 1 | Map | Route selected, Save button | Save sheet |
+| 2 | Save sheet | Name, offline and sync toggles | Saved list |
+| 3 | Saved list | Sort chips, sync state per row | Route detail |
+| 4 | Route detail | Stats and Remove action | Saved list |
+
+## 3. Decision
+
+| Question | Options | Recommendation | Why |
+|----------|---------|----------------|-----|
+| Where do saved routes live? | Local database with sync / server only / GPX files | **Local database with background sync** | Hikers lose signal on the trails they want to follow; last edit wins is enough for one person on two devices |
+
+## 4. Flow
+
+```mermaid
+sequenceDiagram
+  participant H as Hiker
+  participant A as App
+  participant L as Local DB
+  participant S as Sync API
+  H->>A: Tap Save on a route
+  A->>L: Insert route with revision 1
+  A-->>H: Show Saved toast
+  A->>S: Push pending changes
+  S-->>A: Accepted, server revision
+  A->>L: Mark route synced
+```
+
+## 5. Build order
+
+- [x] Feature flag saved_routes, off by default
+- [ ] Local table saved_routes with revision and deleted_at
+- [ ] Push and pull endpoints with revision check
+- [ ] Tombstones kept for 30 days, nightly purge
+- [ ] Save sheet, saved list and route detail screens
+- [ ] Background sync with last edit wins
+- [ ] Enable for the beta group and watch the sync error rate
+
+## 6. Acceptance
+
+- [ ] Save from the map takes two taps or fewer
+- [ ] Saved list opens in airplane mode
+- [ ] Removing a route on one device removes it on the other
+- [ ] A list of 500 routes scrolls without dropped frames
+- [ ] Screen reader announces Saved and Removed
+
+## 7. Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Two devices edit the same route offline | Medium | Low | Last edit wins, keep the older copy in a recently-deleted list |
+| Large saved lists slow the map | Low | Medium | Load the list lazily, never on map start |
+| Tombstones grow without bound | Low | Low | Nightly purge after 30 days |
+
+## 8. Open questions
+
+- Can routes be grouped in folders? Recommended: not in the beta.
+- Default sort of the saved list? Recommended: recently saved.
+- Extras for the beta: share a route link, export as GPX, notes on a saved route.

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/migration/meta.json

@@ -0,0 +1 @@
+{"id":"migration","label":"Migration","description":"Data or system migration plan with phases, cutover checklist, rollback and a risk table.","useWhen":"You move data or a service from an old system to a new one and need a safe cutover and a way back.","hasBoard":false}

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/migration/plan.mdx

@@ -0,0 +1,172 @@
+---
+title: Lantern Ledger - Database Cutover
+status: draft
+needs-snapshot: prep
+needs-replicate: prep, snapshot
+needs-verify: replicate
+needs-cutover: verify
+needs-decommission: cutover
+---
+
+# Lantern Ledger: Move from legacy Postgres 12 to managed Postgres 16
+
+<Callout tone="note" title="How to use this template">
+
+Replace the system names, sizes, dates and owners with your own. Keep the phase structure, the rollback trigger and the cutover checklist: they are what make a migration reviewable. Delete the open questions you have already answered. All names and numbers below are invented.
+
+</Callout>
+
+## Goal
+
+Move the Lantern Ledger billing database (410 GB, 38 tables) from a self-hosted Postgres 12 VM to a managed Postgres 16 cluster with at most 10 minutes of write downtime and no lost invoices.
+
+- Cutover happens in one maintenance window on a Sunday, 02:00 to 04:00 UTC.
+- The old database stays readable and in sync for 14 days as the rollback path.
+- Every row count and a checksum of the money columns match before traffic moves.
+
+## Decision
+
+<Decision title="How do we move the data?" question="Which method gets 410 GB across with the shortest write freeze?" options={[
+  { id: "logical", label: "Logical replication, then switch", detail: "Initial copy runs live, changes stream until cutover. Freeze is minutes.", recommended: true },
+  { id: "dump", label: "Dump and restore in the window", detail: "Simple, but the freeze would last about 5 hours at our measured speed." },
+  { id: "vendor", label: "Vendor migration service", detail: "Least work for us, but opaque failure modes and per-GB cost." },
+]}>
+
+Logical replication keeps the freeze short and lets us verify the target for days before the switch. The cost is that sequences and large objects need a manual step at cutover, which is on the checklist.
+
+</Decision>
+
+## Timeline
+
+<Mermaid label="Phases and dates" source={"gantt\n  dateFormat YYYY-MM-DD\n  axisFormat %d %b\n  section Prepare\n  Inventory and schema diff     :prep, 2026-11-02, 5d\n  Target cluster and network    :infra, 2026-11-04, 4d\n  section Copy\n  Snapshot and initial load     :snap, 2026-11-09, 3d\n  Streaming replication         :repl, after snap, 7d\n  section Prove\n  Verification and dry run      :ver, 2026-11-16, 4d\n  section Cutover\n  Maintenance window            :crit, cut, 2026-11-22, 1d\n  Rollback watch                :watch, after cut, 14d\n  section Close\n  Decommission old VM           :done, dec, 2026-12-07, 2d"} />
+
+## Phases
+
+<Table title="Phase plan" columns={["Phase", "Outcome", "Exit criterion", "Owner"]} rows={[
+  ["1 Prepare", "Inventory, schema diff, target cluster", "Schema applies cleanly on PG 16", "Mara (platform)"],
+  ["2 Copy", "Snapshot loaded, replication streaming", "Lag under 5 seconds for 24 hours", "Mara (platform)"],
+  ["3 Prove", "Verification and one full dry run", "Counts and checksums match, dry run under 10 minutes", "Joss (backend)"],
+  ["4 Cutover", "Writes frozen, final sync, traffic switched", "Smoke tests green, error rate at baseline", "Mara and Joss"],
+  ["5 Watch", "Old database kept as warm fallback", "14 quiet days, no rollback trigger hit", "Joss (backend)"],
+  ["6 Close", "Old VM snapshotted and removed", "Sign-off from finance on the final report", "Ines (finance ops)"],
+]} />
+
+## Build map
+
+### Prepare {#prep}
+
+<Checklist title="Prepare tasks" items={[
+  { label: "Inventory tables, extensions and large objects", checked: true },
+  { label: "Diff schema between PG 12 and PG 16, fix incompatibilities", checked: true },
+  { label: "Provision the managed cluster and private network peering" },
+  { label: "Lower DNS TTL for the database alias to 60 seconds" },
+]} />
+
+<ImplementationMap files={[
+  { path: "migration/schema_diff.sql", change: "added", note: "Reviewed differences and fixes" },
+  { path: "infra/db-cluster.tf", change: "added", note: "Managed cluster, replicas, backups" },
+]} />
+
+### Snapshot and initial load {#snapshot}
+
+<Checklist title="Snapshot tasks" items={[
+  { label: "Create the publication on the source for all 38 tables" },
+  { label: "Run the initial copy with four parallel workers" },
+  { label: "Record the start position and row counts" },
+]} />
+
+<ImplementationMap files={[
+  { path: "migration/publication.sql", change: "added", note: "Publication and replication slot" },
+  { path: "migration/initial_load.sh", change: "added", note: "Parallel table copy with logging" },
+]} />
+
+### Replication {#replicate}
+
+<Checklist title="Replication tasks" items={[
+  { label: "Subscribe and let changes stream" },
+  { label: "Alert when lag exceeds 30 seconds" },
+  { label: "Plan sequence resync for cutover" },
+]} />
+
+<ImplementationMap files={[
+  { path: "migration/subscription.sql", change: "added", note: "Subscription on the target" },
+  { path: "ops/alerts/replication-lag.yml", change: "added", note: "Lag alert and runbook link" },
+]} />
+
+### Verify {#verify}
+
+<Checklist title="Verify tasks" items={[
+  { label: "Row counts equal on all 38 tables" },
+  { label: "Checksum of amount and tax columns equal" },
+  { label: "Replay one week of read queries against the target" },
+  { label: "Full dry run on a clone, stopwatch under 10 minutes" },
+]} />
+
+<ImplementationMap files={[
+  { path: "migration/verify.py", change: "added", note: "Counts and checksums per table" },
+  { path: "migration/replay_reads.sh", change: "added", note: "Read replay and latency compare" },
+]} />
+
+### Cutover {#cutover}
+
+<Checklist title="Cutover checklist" items={[
+  { label: "T-60 min: status page notice posted and on-call confirmed" },
+  { label: "T-30 min: last backup of the source verified restorable" },
+  { label: "T-10 min: pause the invoice scheduler and background workers" },
+  { label: "T-0: set source to read-only, confirm zero active writers" },
+  { label: "T+2 min: replication lag is zero, final counts match" },
+  { label: "T+4 min: resync sequences, enable constraints, run ANALYZE" },
+  { label: "T+6 min: switch the DNS alias and app config to the target" },
+  { label: "T+8 min: start workers, run the smoke test suite" },
+  { label: "T+10 min: go or rollback decision, announce on the status page" },
+]} />
+
+<ImplementationMap files={[
+  { path: "migration/cutover_runbook.md", change: "added", note: "Minute by minute script with owners" },
+  { path: "migration/sequences.sql", change: "added", note: "Sequence resync for every serial column" },
+]} />
+
+### Decommission {#decommission}
+
+<Checklist title="Decommission tasks" items={[
+  { label: "Stop reverse replication after 14 quiet days" },
+  { label: "Take a final snapshot and archive it for one year" },
+  { label: "Delete the old VM and the replication slot" },
+]} />
+
+<ImplementationMap files={[
+  { path: "migration/final_report.md", change: "added", note: "Counts, timings, incidents, sign-off" },
+]} />
+
+## Agent trail
+
+<AgentTrail />
+
+## Rollback
+
+<Callout tone="warning" title="Rollback trigger and path">
+
+Roll back if any of these hold within the first 24 hours: smoke tests fail twice, p95 write latency is above 400 ms for 10 minutes, or any checksum differs. Path: freeze writes on the target, point the alias back to the old VM (kept in sync by reverse replication), unpause the workers, post a status update. Target time to roll back: 8 minutes. After 24 hours, a rollback needs a fresh GO from the owner.
+
+</Callout>
+
+## Risks
+
+<Table title="Risk register" columns={["Risk", "Likelihood", "Impact", "Mitigation"]} rows={[
+  ["Replication lag grows during the Friday batch", "Medium", "High", "Schedule the window after the batch, alert at 30 s"],
+  ["Sequences not resynced, duplicate key errors", "Medium", "High", "Scripted resync on the checklist, tested in the dry run"],
+  ["Extension missing on managed Postgres", "Low", "High", "Found in the inventory phase, replace before the copy"],
+  ["DNS caches keep old address", "Medium", "Medium", "TTL 60 s a week ahead, app uses the alias only"],
+  ["Cutover runs longer than the window", "Low", "Medium", "Dry run timing, hard stop at T+20 min triggers rollback"],
+]} />
+
+## Open questions
+
+<QuestionForm title="Open Questions" questions={[
+  { title: "How long do we keep the old VM?", mode: "single", options: [
+    { label: "14 days", recommended: true }, { label: "30 days" }, { label: "Delete right after cutover" } ] },
+  { title: "Who can call the rollback?", mode: "single", options: [
+    { label: "The on-call engineer", recommended: true }, { label: "Only the migration owner" } ] },
+  { title: "Which extras do we add to the window?", mode: "multi", options: [
+    { label: "Upgrade the connection pooler" }, { label: "Enable query insights" }, { label: "Rotate database passwords" } ] },
+]} />

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/migration/standard.md

@@ -0,0 +1,100 @@
+# Lantern Ledger: Move from legacy Postgres 12 to managed Postgres 16
+
+> Template guidance: replace the invented system names, sizes, dates and owners. Keep the phases, rollback trigger and cutover checklist. All names and numbers are invented.
+
+**Status:** draft
+
+## Goal
+
+Move the Lantern Ledger billing database (410 GB, 38 tables) from a self-hosted Postgres 12 VM to a managed Postgres 16 cluster with at most 10 minutes of write downtime and no lost invoices.
+
+- Cutover happens in one maintenance window on a Sunday, 02:00 to 04:00 UTC.
+- The old database stays readable and in sync for 14 days as the rollback path.
+- Every row count and a checksum of the money columns match before traffic moves.
+
+## Decision
+
+| Question | Options | Recommendation | Why |
+|---|---|---|---|
+| How do we move the data? | Logical replication / dump and restore / vendor service | **Logical replication, then switch** | Freeze is minutes; the target can be verified for days. Sequences and large objects need a manual step at cutover. |
+
+## Timeline
+
+```mermaid
+gantt
+  dateFormat YYYY-MM-DD
+  axisFormat %d %b
+  section Prepare
+  Inventory and schema diff     :prep, 2026-11-02, 5d
+  Target cluster and network    :infra, 2026-11-04, 4d
+  section Copy
+  Snapshot and initial load     :snap, 2026-11-09, 3d
+  Streaming replication         :repl, after snap, 7d
+  section Prove
+  Verification and dry run      :ver, 2026-11-16, 4d
+  section Cutover
+  Maintenance window            :crit, cut, 2026-11-22, 1d
+  Rollback watch                :watch, after cut, 14d
+  section Close
+  Decommission old VM           :done, dec, 2026-12-07, 2d
+```
+
+## Phases
+
+| Phase | Outcome | Exit criterion | Owner |
+|---|---|---|---|
+| 1 Prepare | Inventory, schema diff, target cluster | Schema applies cleanly on PG 16 | Mara (platform) |
+| 2 Copy | Snapshot loaded, replication streaming | Lag under 5 seconds for 24 hours | Mara (platform) |
+| 3 Prove | Verification and one full dry run | Counts and checksums match, dry run under 10 minutes | Joss (backend) |
+| 4 Cutover | Writes frozen, final sync, traffic switched | Smoke tests green, error rate at baseline | Mara and Joss |
+| 5 Watch | Old database kept as warm fallback | 14 quiet days, no rollback trigger hit | Joss (backend) |
+| 6 Close | Old VM snapshotted and removed | Sign-off from finance on the final report | Ines (finance ops) |
+
+## Prepare tasks
+
+- [x] Inventory tables, extensions and large objects
+- [x] Diff schema between PG 12 and PG 16, fix incompatibilities
+- [ ] Provision the managed cluster and private network peering
+- [ ] Lower DNS TTL for the database alias to 60 seconds
+
+## Copy and verify tasks
+
+- [ ] Create the publication on the source for all 38 tables
+- [ ] Run the initial copy with four parallel workers
+- [ ] Subscribe, let changes stream, alert when lag exceeds 30 seconds
+- [ ] Row counts and money-column checksums equal on all tables
+- [ ] Replay one week of read queries against the target
+- [ ] Full dry run on a clone, stopwatch under 10 minutes
+
+## Cutover checklist
+
+- [ ] T-60 min: status page notice posted and on-call confirmed
+- [ ] T-30 min: last backup of the source verified restorable
+- [ ] T-10 min: pause the invoice scheduler and background workers
+- [ ] T-0: set source to read-only, confirm zero active writers
+- [ ] T+2 min: replication lag is zero, final counts match
+- [ ] T+4 min: resync sequences, enable constraints, run ANALYZE
+- [ ] T+6 min: switch the DNS alias and app config to the target
+- [ ] T+8 min: start workers, run the smoke test suite
+- [ ] T+10 min: go or rollback decision, announce on the status page
+
+## Rollback
+
+**Trigger (first 24 hours):** smoke tests fail twice, p95 write latency above 400 ms for 10 minutes, or any checksum differs.
+**Path:** freeze writes on the target, point the alias back to the old VM (kept in sync by reverse replication), unpause workers, post a status update. Target time: 8 minutes. After 24 hours a rollback needs a fresh GO from the owner.
+
+## Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| Replication lag grows during the Friday batch | Medium | High | Schedule the window after the batch, alert at 30 s |
+| Sequences not resynced, duplicate key errors | Medium | High | Scripted resync on the checklist, tested in the dry run |
+| Extension missing on managed Postgres | Low | High | Found in the inventory phase, replace before the copy |
+| DNS caches keep old address | Medium | Medium | TTL 60 s a week ahead, app uses the alias only |
+| Cutover runs longer than the window | Low | Medium | Dry run timing, hard stop at T+20 min triggers rollback |
+
+## Open questions
+
+- How long do we keep the old VM? 14 days (recommended) / 30 days / delete right after cutover
+- Who can call the rollback? The on-call engineer (recommended) / only the migration owner
+- Which extras join the window? Connection pooler upgrade / query insights / password rotation

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/recap/meta.json

@@ -0,0 +1 @@
+{"id":"recap","label":"Visual recap","description":"A post-work recap with what changed, why, how it was verified and follow-ups.","useWhen":"Work is finished and reviewers or teammates need a quick, visual summary of the change.","hasBoard":false}

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/recap/plan.mdx

@@ -0,0 +1,67 @@
+---
+title: Retry failed exports automatically
+subtitle: Failed Lanternfish exports now retry with backoff and show their state to the customer. Invented example.
+kind: recap
+pr: "#142"
+branch: feat/export-retry
+base: main
+commit: 4c8a1f0
+files: 5
+additions: 318
+deletions: 24
+author: sample-author
+date: 2026-03-09
+---
+
+<Callout tone="note" title="How to use this template">
+
+Replace the Lanternfish example with your own change: update the frontmatter chips (PR, branch, commit, counts), rewrite the summary and the reason, list the files you really touched, and record the checks you actually ran. Delete sections you do not need. All names and numbers here are invented.
+
+</Callout>
+
+## What changed
+
+Failed exports used to disappear: the job died, the customer saw a spinner and support had to re-run it by hand. Exports now retry up to three times with growing delays, and the export list shows each job as Queued, Running, Retrying or Failed.
+
+- Retry delays are 1, 5 and 25 minutes.
+- A job that exhausts its retries stays visible with the last error message.
+- Customers can re-run a failed export with one click.
+
+<ImplementationMap title="Changed files" files={[
+  { path: "worker/export-runner.ts", change: "modified", note: "Wrap the run in retry with backoff" },
+  { path: "worker/retry-policy.ts", change: "added", note: "Delay table and attempt counter" },
+  { path: "api/exports/list.ts", change: "modified", note: "Return state and last error" },
+  { path: "app/exports/export-row.tsx", change: "modified", note: "State badge and re-run button" },
+  { path: "tests/export-retry.test.ts", change: "added", note: "Backoff, exhaustion and re-run cases" },
+]} />
+
+## Why
+
+<Table title="Reasons" columns={["Problem", "Evidence", "Fixed by"]} rows={[
+  ["About 4 percent of exports failed once", "Support ticket sample", "Automatic retry"],
+  ["Customers could not tell failed from slow", "Five tickets asking if an export was stuck", "Visible job state"],
+  ["Support re-ran jobs by hand", "About 6 manual re-runs per week", "Re-run button"],
+]} />
+
+## How verified
+
+<Checklist title="Checks">
+- [x] Unit tests for backoff delays and attempt limit
+- [x] Integration test: a job that fails twice then succeeds ends as Done
+- [x] Manual run on staging with a forced failure, state badge changed as expected
+- [ ] Load test with 300 queued jobs (not run yet)
+</Checklist>
+
+## Follow-ups
+
+<Callout tone="warn" title="Not done in this change">
+
+Customers are not emailed when an export finally fails, and the retry delays are fixed in code rather than configurable. Both are listed as follow-up tasks.
+
+</Callout>
+
+<Checklist title="Follow-ups">
+- [ ] Email the customer after the final failure
+- [ ] Make the delay table configurable per plan
+- [ ] Run the 300 job load test on staging
+</Checklist>

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/recap/standard.md

@@ -0,0 +1,49 @@
+# Recap: Retry failed exports automatically
+
+> Invented example. Replace every fact with your own change.
+
+**PR:** #142  **Branch:** feat/export-retry into main  **Commit:** 4c8a1f0  **Date:** 2026-03-09  **Size:** 5 files, +318 / -24
+
+## What changed
+
+Failed exports used to disappear: the job died, the customer saw a spinner and support had to re-run it by hand. Exports now retry up to three times with growing delays (1, 5 and 25 minutes), and the export list shows each job as Queued, Running, Retrying or Failed. A job that exhausts its retries stays visible with the last error and can be re-run with one click.
+
+| File | Change | Note |
+|------|--------|------|
+| worker/export-runner.ts | modified | Wrap the run in retry with backoff |
+| worker/retry-policy.ts | added | Delay table and attempt counter |
+| api/exports/list.ts | modified | Return state and last error |
+| app/exports/export-row.tsx | modified | State badge and re-run button |
+| tests/export-retry.test.ts | added | Backoff, exhaustion and re-run cases |
+
+```mermaid
+stateDiagram-v2
+  [*] --> Queued
+  Queued --> Running
+  Running --> Done
+  Running --> Retrying: error
+  Retrying --> Running: after delay
+  Retrying --> Failed: attempts exhausted
+  Failed --> Queued: re-run
+```
+
+## Why
+
+| Problem | Evidence | Fixed by |
+|---------|----------|----------|
+| About 4 percent of exports failed once | Support ticket sample | Automatic retry |
+| Customers could not tell failed from slow | Five tickets asking if an export was stuck | Visible job state |
+| Support re-ran jobs by hand | About 6 manual re-runs per week | Re-run button |
+
+## How verified
+
+- [x] Unit tests for backoff delays and attempt limit
+- [x] Integration test: a job that fails twice then succeeds ends as Done
+- [x] Manual run on staging with a forced failure
+- [ ] Load test with 300 queued jobs (not run yet)
+
+## Follow-ups
+
+- [ ] Email the customer after the final failure
+- [ ] Make the delay table configurable per plan
+- [ ] Run the 300 job load test on staging