String-sg · natashaannn · May 21, 2026
diff --git a/docs/CURRENT_SPRINT_ISSUES.md b/docs/CURRENT_SPRINT_ISSUES.md
diff --git a/docs/FORK_MIGRATION.md b/docs/FORK_MIGRATION.md
diff --git a/docs/fork-migration-issues/_index.md b/docs/fork-migration-issues/_index.md
@@ -0,0 +1,43 @@
+# Fork Migration Issues Index
+
+Source of truth for migration layer status and ordering.
+Full layer details: `docs/FORK_MIGRATION.md`.
+Active sprint conflicts: `docs/CURRENT_SPRINT_ISSUES.md`.
+
+Last updated: 2026-05-21
+
+---
+
+## Issues
+
+| ID | File | Title | Status | Blocks on PRs | Blocks on issues |
+|----|------|-------|--------|---------------|-----------------|
+| MIGRATION-01 | [issue-01-tooling-config-delta.md](issue-01-tooling-config-delta.md) | Tooling and config delta | `blocked` | PR #182, PR #157 | — |
+| MIGRATION-02 | [issue-02-go-pg-bff.md](issue-02-go-pg-bff.md) | Go: PG BFF layer | `blocked` | PR #181 | — |
+| MIGRATION-03 | [issue-03-web-api-client.md](issue-03-web-api-client.md) | Web: API client layer | `ready` | — | — |
+| MIGRATION-04 | [issue-04-shadcn-ui-delta.md](issue-04-shadcn-ui-delta.md) | Web: shadcn UI primitives delta | `blocked` | PR #182 | MIGRATION-01 |
+| MIGRATION-05 | [issue-05-posts-module.md](issue-05-posts-module.md) | Web: Posts module | `pending` | — | MIGRATION-02, 03, 04, 07 |
+| MIGRATION-06 | [issue-06-groups-module.md](issue-06-groups-module.md) | Web: Groups module | `pending` | — | MIGRATION-02, 03, 04, 07 |
+| MIGRATION-07 | [issue-07-shared-comms-selectors.md](issue-07-shared-comms-selectors.md) | Web: Shared comms selectors | `pending` | — | MIGRATION-03, 04 |
+| MIGRATION-08 | [issue-08-docs.md](issue-08-docs.md) | Documentation and planning docs | `ready` | — | — |
+
+---
+
+## Landing order
+
+```
+[PR #182 merges] --> MIGRATION-01, MIGRATION-04
+[PR #181 merges] --> MIGRATION-02
+MIGRATION-03     --> (draft now, no blockers)
+MIGRATION-08     --> (draft now, no blockers)
+
+After MIGRATION-01, 02, 03, 04 merged:
+  --> MIGRATION-07
+  --> MIGRATION-05 (parallel with 06)
+  --> MIGRATION-06 (parallel with 05)
+```
+
+## What can be started right now
+
+- **MIGRATION-03** (Web: API client) — no blockers, purely additive new directory
+- **MIGRATION-08** (Docs) — no blockers, markdown only
diff --git a/docs/fork-migration-issues/_template.md b/docs/fork-migration-issues/_template.md
@@ -0,0 +1,82 @@
+# Migration Issue Template
+
+This template defines the structure for all fork migration issues in this folder.
+Every issue file must follow this structure exactly so that a coding agent with no prior
+context can pick it up and complete it without back-and-forth.
+
+---
+
+## MIGRATION-XX — [Title]
+
+### Status
+`blocked` | `ready` | `in-progress` | `done`
+
+### Blocking sprint PRs
+List every open sprint PR that must merge into `main` before this issue can start.
+Check `docs/CURRENT_SPRINT_ISSUES.md` for current PR URLs and merge status.
+If none, write: None.
+
+### Prerequisite migration issues
+List every migration issue (by ID) whose PR must be merged into `main` before this
+issue branch can be created. If none, write: None.
+
+### Background
+2-4 sentences explaining what this migration issue is adding and why it exists.
+Reference the relevant layer in `docs/FORK_MIGRATION.md`. Do not assume the reader
+has read that doc.
+
+### Repo paths
+- **Fork (source):** `d:\Environment\tw\teacher-workspace-pg\`
+- **Target (this repo):** `d:\Environment\tw\teacher-workspace\`
+
+All relative file paths in the Steps section are relative to these roots.
+
+### Starting point
+Before creating the branch, verify the following are true in `main`:
+- [ ] All blocking sprint PRs listed above have been merged
+- [ ] All prerequisite migration issues listed above have been merged
+- [ ] `git pull origin main` is clean
+
+Branch off `main` after all the above are confirmed.
+
+---
+
+### Steps
+
+Numbered steps the agent must execute in order. Each step must be atomic and
+verifiable. Prefer explicit commands over vague instructions.
+
+#### Step N — [Step title]
+What to do, including exact commands, file paths, and any modification instructions.
+
+---
+
+### Files to copy verbatim
+Files that can be copied from the fork to the target without modification.
+List as: `<fork-relative-path>` → `<target-relative-path>`
+
+### Files to copy with modifications
+Files that must be copied and then edited. For each file, state what to change and why.
+
+### Files to skip
+Files present in the fork that must NOT be copied. State why.
+
+### New packages
+Exact `pnpm add` commands to run.
+
+---
+
+### Acceptance criteria
+Checkable conditions that confirm the issue is complete.
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+### Branch name
+`chore/migration-XX-[short-description]`
+
+### PR title
+`chore(migration): [short description matching CONTRIBUTING.md conventions]`
+
+### PR summary template
+One paragraph the agent can use as the PR summary section. It should explain what
+the PR adds and reference `docs/FORK_MIGRATION.md` Layer N.
diff --git a/docs/fork-migration-issues/issue-01-tooling-config-delta.md b/docs/fork-migration-issues/issue-01-tooling-config-delta.md
@@ -0,0 +1,166 @@
+# MIGRATION-01 — Tooling and config delta
+
+### Status
+`blocked`
+
+### Blocking sprint PRs
+- [PR #182](https://github.com/String-sg/teacher-workspace/pull/182) `refactor(web): replace Flow DS with shadcn Base UI` — adds `components.json`, shadcn npm packages, `web/lib/utils.ts`. Must merge before this issue so we only add the delta.
+- [PR #157](https://github.com/String-sg/teacher-workspace/pull/157) `feat(db): add Atlas declarative schema, Postgres 18, and sqlc queries` — adds `docker-compose.yaml` (Postgres). Must merge before this issue so we can name the PGW compose file without collision.
+
+### Prerequisite migration issues
+None.
+
+### Background
+The fork adds test infrastructure (Vitest + React Testing Library), a renamed docker-compose
+file for local PGW development, and several root-level config files that are not present in
+this repo. Much of the shadcn setup (components.json, shadcn npm packages, web/lib/utils.ts)
+is being done by PR #182 as sprint work. This issue adds only what remains after that PR merges.
+See `docs/FORK_MIGRATION.md` Layer 1.
+
+### Repo paths
+- **Fork (source):** `d:\Environment\tw\teacher-workspace-pg\`
+- **Target (this repo):** `d:\Environment\tw\teacher-workspace\`
+
+### Starting point
+Before creating the branch, verify the following are true in `main`:
+- [ ] PR #182 has been merged
+- [ ] PR #157 has been merged
+- [ ] `git pull origin main` is clean
+
+---
+
+### Steps
+
+#### Step 1 — Check what PR #182 already landed
+Run the following and note what is already present in `main`:
+```
+ls web/lib/
+ls web/components/ui/
+cat components.json
+cat package.json | grep -E "class-variance|clsx|tailwind-merge|lucide|base-ui|radix|tw-animate"
+```
+Do NOT re-add anything already present. The items below marked "skip if present" should
+only be added if they are missing after PR #182.
+
+#### Step 2 — Add Vitest test infrastructure
+Copy the following files verbatim from the fork:
+- `vitest.config.ts` → `vitest.config.ts`
+- `web/test/setup.ts` → `web/test/setup.ts` (create `web/test/` directory if absent)
+
+Add dev dependencies:
+```
+pnpm add -D vitest @vitest/ui @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom
+```
+
+Add the pnpm override to `package.json` (inside the `"pnpm"` key, create it if absent):
+```json
+"pnpm": {
+  "overrides": {
+    "@tiptap/pm": "3.22.3"
+  }
+}
+```
+
+Add test scripts to `package.json` `"scripts"` section:
+```json
+"test": "vitest run",
+"test:watch": "vitest"
+```
+
+Add lint script (if not already present from sprint work):
+```json
+"golint": "golangci-lint run"
+```
+
+Verify the test runner works before proceeding:
+```
+pnpm test
+```
+There are no test files yet in this repo, so Vitest will report "No test files found" —
+that is expected and passing.
+
+#### Step 3 — Add sonner package (skip if already present)
+`sonner` is the toast notification library used by `web/lib/notify.ts`. Check if it was
+added by PR #182. If not:
+```
+pnpm add sonner
+```
+
+#### Step 4 — Add the PGW docker-compose and MySQL config
+The fork includes a `docker-compose.yml` and `docker/` directory for running a local
+PGW MySQL replica during development. PR #157 already added a `docker-compose.yaml`
+(Postgres) to this repo. To avoid naming confusion, copy the fork's compose file with a
+distinct name:
+
+```
+cp d:\Environment\tw\teacher-workspace-pg\docker-compose.yml docker-compose.pgw.yml
+cp -r d:\Environment\tw\teacher-workspace-pg\docker\ docker\
+```
+
+Open `docker-compose.pgw.yml` and verify it does not conflict with any service names
+already defined in `docker-compose.yaml`. If there are collisions on service names
+(e.g. both define a service called `db`), rename the PGW service to `pgw-db` and update
+any volume references inside the same file accordingly.
+
+#### Step 5 — Copy remaining root config files
+Copy verbatim from fork:
+- `.mcp.json` → `.mcp.json`
+
+The fork also has `DESIGN.md` and `TODOS.md` at the root. These are handled separately
+in MIGRATION-08 (Docs). Skip them here.
+
+#### Step 6 — Remove the `air` dev script (coordinate with team first)
+The fork removed the `dev:all` script and the `go.mod` tool directive for `air` in favour
+of a plain `go run` workflow. Before removing these from this repo, confirm with the team
+that no one is actively using `go tool air` for development. If the team agrees, remove:
+- The `"dev:all"` script from `package.json`
+- The `tool github.com/air-verse/air` line from `go.mod`
+
+If the team is not ready to drop `air`, skip this step and leave a comment in the PR.
+
+---
+
+### Files to copy verbatim
+- `vitest.config.ts` → `vitest.config.ts`
+- `web/test/setup.ts` → `web/test/setup.ts`
+- `.mcp.json` → `.mcp.json`
+- `docker-compose.yml` → `docker-compose.pgw.yml` (rename on copy — see Step 4)
+- `docker/` → `docker/` (entire directory)
+
+### Files to skip
+- `components.json` — covered by PR #182 (check before adding)
+- `DESIGN.md` — handled by MIGRATION-08
+- `TODOS.md` — handled by MIGRATION-08
+- `.planning/` — handled by MIGRATION-08
+- `docker-compose.yml` (original name) — rename to `docker-compose.pgw.yml` to avoid collision
+
+### New packages
+```
+pnpm add sonner
+pnpm add -D vitest @vitest/ui @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom
+```
+
+---
+
+### Acceptance criteria
+- [ ] `pnpm test` runs and exits 0 (no test files found is acceptable)
+- [ ] `vitest.config.ts` exists at repo root
+- [ ] `web/test/setup.ts` exists
+- [ ] `docker-compose.pgw.yml` exists and does not share service names with `docker-compose.yaml`
+- [ ] `docker/` directory exists with MySQL config copied from fork
+- [ ] `.mcp.json` exists at repo root
+- [ ] `package.json` contains `"test"` and `"test:watch"` scripts
+- [ ] `pnpm install` runs without errors
+
+### Branch name
+`chore/migration-01-tooling-config-delta`
+
+### PR title
+`chore(migration): add Vitest, test setup, PGW docker config, and remaining tooling delta`
+
+### PR summary template
+Adds the tooling and configuration items from the fork (`teacher-workspace-pg`) that were
+not covered by the concurrent sprint work in PR #182 and PR #157. Specifically: Vitest +
+React Testing Library test infrastructure, the `docker-compose.pgw.yml` and `docker/`
+directory for local PGW MySQL development, and `.mcp.json`. See `docs/FORK_MIGRATION.md`
+Layer 1 for the full list of what was and was not included.