Scrum4Me/docs/old/plans/auto-pr-deploy-sync.md

Plan — Auto-PR + selectieve deploy-controle + sync-zicht (end-to-end batch flow)

Bij merge: dit plan verplaatsen naar docs/plans/auto-pr-deploy-sync.md conform feedback-memory (plans in docs/plans/).

Context

Drie samenhangende problemen rond de "idee → uitvoeren"-keten:

1. Worker stopt bij commit. De Scrum4Me NAS-worker werkt lokaal: commits blijven op de machine staan totdat de gebruiker zelf pusht en een PR aanmaakt. Voor batch-uitvoer van story-jobs is dit een harde menselijke gate.
2. Deploy is alles-of-niets. .github/workflows/ci.yml deployt nu elke push naar main automatisch naar productie en elke PR naar preview. vercel.json heeft geen git.deploymentEnabled: false, dus Vercel's eigen Git-integratie deployt waarschijnlijk parallel mee → dubbele deploys en geen selectieve controle.
3. Geen zicht op voortgang per Idea/PBI. Concreet getest geval: PBI-33 wordt nu de eerste sprint-batch — er is geen git-voetafdruk (geen branch/commit/PR met "PBI-33"), geen activiteitenlog-entry, en geen UI-pagina die per Story toont of er een ClaudeJob loopt, een commit gepusht is, of een PR open/merged is. De data zit in Story.status, ClaudeJob.pushed_at/branch/pr_url, Pbi.pr_url/pr_merged_at — er is alleen geen view die het joint.

Doel: de complete keten plan → job → commit → push → PR → auto-merge → deploy in één coherent ontwerp leggen, met (a) selectieve deploy-controle als veiligheidsklep en (b) een sync-tab die per Idea laat zien wat er werkelijk in git/PR-land gebeurd is.

Vastgelegde keuzes

Deploy-controle

1. Mechanisme: PR-labels (B) + path-filter (C) gecombineerd.
2. Eigenaar: GitHub Actions-workflow (A). Vercel Git-integratie uit.
3. Defaults: PR → preview, push naar main → productie.
4. Override-richtingen:
   • skip-deploy label: voorkomt preview-deploy op een PR.
   • force-deploy label: forceert deploy ook als path-filter doc-only zegt.

Auto-PR (uit IDEA-007-grill)

5. Triggers in worker: na elke succesvolle update_job_status('done') pusht de worker; na laatste story van een PBI maakt de worker een PR aan en activeert auto-merge (SQUASH).
6. Auth: GITHUB_TOKEN als omgevingsvariabele op de worker; geen UI of GitHub App in v1.
7. Foutafhandeling: push/PR-aanmaak-fail → update_job_status('failed', error: …); geen force-push, geen automatische retry.

Interactie tussen beide

8. Worker-PRs gebruiken hetzelfde labelsysteem als alle andere PRs. Default = preview deploy, auto-merge wacht op CI groen, na merge prod-deploy (mits path-filter zegt "code"). De worker zet geen labels automatisch — als je batch-output zonder preview wilt mergen moet je skip-deploy zelf toevoegen, of preview later uitzetten via een product-instelling (out-of-scope v1).
9. Implementatievolgorde: eerst deploy-controle (infra, onafhankelijk), daarna auto-PR (afhankelijk van stabiele deploy-flow).

Architectuur in één plaat

                                      auto-merge wacht op
[story-job DONE] ─push branch─┐       deploy-preview groen
                              ▼              │
[laatste story?]──ja──[PR + auto-merge]──CI──┴──merge naar main
                                              │
                                       [job: ci] altijd
                                              │
                                       [paths-filter]
                                              │
                                              ├ PR    → deploy-preview
                                              │        if code && !skip-deploy
                                              │        || force-deploy
                                              │
                                              └ push  → deploy-production
                                                       if code

---

Deel A — Deploy-controle

A.1 vercel.json — Vercel Git-deploy uitzetten

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "git": { "deploymentEnabled": false },
  "crons": [
    { "path": "/api/cron/expire-questions", "schedule": "0 4 * * *" },
    { "path": "/api/cron/cleanup-agent-artifacts", "schedule": "0 3 * * *" }
  ]
}

Effect: Vercel deployt niet meer automatisch op git-events. Alleen vercel deploy vanuit de workflow (met VERCEL_TOKEN) maakt nog deployments.

A.2 .github/workflows/ci.yml — path-filter + label-checks

Triggers uitbreiden met workflow_dispatch:

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:
    inputs:
      target:
        type: choice
        description: Deploy target
        options: [preview, production]
        default: preview

Nieuwe job vóór de deploy-jobs:

  changes:
    name: Detect deploy-relevant changes
    runs-on: ubuntu-latest
    needs: ci
    outputs:
      code: ${{ steps.filter.outputs.code }}
    steps:
      - uses: actions/checkout@v5
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            code:
              - 'app/**'
              - 'components/**'
              - 'lib/**'
              - 'actions/**'
              - 'stores/**'
              - 'prisma/**'
              - 'public/**'
              - 'package.json'
              - 'package-lock.json'
              - 'next.config.ts'
              - 'tsconfig.json'
              - 'vercel.json'
              - 'proxy.ts'
              - 'middleware.ts'
              - '.github/workflows/**'

deploy-preview if-conditie aanpassen:

  deploy-preview:
    needs: [ci, changes]
    if: |
      github.event_name == 'pull_request' && (
        (needs.changes.outputs.code == 'true'
         && !contains(github.event.pull_request.labels.*.name, 'skip-deploy'))
        || contains(github.event.pull_request.labels.*.name, 'force-deploy')
      )

deploy-production if-conditie aanpassen:

  deploy-production:
    needs: [ci, changes]
    if: |
      github.ref == 'refs/heads/main'
      && github.event_name == 'push'
      && needs.changes.outputs.code == 'true'

Nieuwe deploy-manual job voor workflow_dispatch met inputs.target → vercel deploy of vercel deploy --prod.

A.3 GitHub-labels aanmaken

gh label create skip-deploy  --color BFBFBF --description "Preview-deploy overslaan"
gh label create force-deploy --color 0E8A16 --description "Forceer deploy ondanks path-filter"

A.4 Documentatie

docs/runbooks/deploy-control.md — triggers, labels, path-filter, voorbeelden. CLAUDE.md § Deployment-regel verwijst naar runbook.

---

Deel B — Auto-PR (worker → GitHub)

B.1 Acceptatiecriteria (uit IDEA-007)

• AC 1 — Push per story: Na succesvolle update_job_status('done') pusht de worker via HTTPS (https://$GITHUB_TOKEN@github.com/…) naar origin. Push-timestamp via nieuwe MCP-call in ClaudeJob.pushed_at.
• AC 2 — Detectie laatste story: Nieuwe MCP-call check_pbi_complete retourneert { complete: boolean, pbi_id }.
• AC 3 — PR aanmaken: Op complete: true POST naar /repos/{owner}/{repo}/pulls; titel/body uit PBI-naam + voltooide stories; PR-URL via set_pbi_pr.
• AC 4 — Auto-merge activeren: Direct na PR-aanmaak GraphQL enablePullRequestAutoMerge (SQUASH).
• AC 5 — Foutafhandeling: push/PR-fail → update_job_status('failed', error); PR-URL blijft bewaard voor handmatige inspectie.

B.2 Server-side wijzigingen (Scrum4Me-repo)

Velden bestaan al in schema:

• Product.auto_pr Boolean @default(false) (regel 176)
• Pbi.pr_url String? + Pbi.pr_merged_at DateTime? (regel 207–208)
• ClaudeJob.pushed_at DateTime? + ClaudeJob.pr_url String? + ClaudeJob.branch String? (regel 335, 338, 339)

Geen migratie nodig.

Server actions / REST: bestaande set_pbi_pr en mark_pbi_pr_merged MCP-tools blijven. Nieuwe action:

• actions/jobs.ts → recordJobPushedAtAction(jobId) voor pushed_at-write (als die nog niet via MCP gaat).

B.3 MCP-laag (scrum4me-mcp-repo)

Nieuwe tool:

• check_pbi_complete(pbi_id) → { complete: boolean, pbi_id }. Leest alle ClaudeJobs gelinkt aan PBI; aggregeert status. complete = true als alle story-jobs status DONE hebben.

Uitbreiding bestaande tool:

• update_job_status: bij status: 'done' ook pushed_at accepteren (worker geeft timestamp door).
• set_pbi_pr: ongewijzigd, bestaat al.

Schema-drift watchdog (docs/runbooks/mcp-integration.md) moet groen voor merge.

B.4 Worker-laag (lokaal Claude-CLI worker)

Nieuwe stappen na elke story:

1. update_job_status('done', pushed_at: null)  ← bestaand
2. git push https://$GITHUB_TOKEN@github.com/$OWNER/$REPO.git $BRANCH
3. record_pushed_at(job_id, now)               ← nieuwe MCP-call
4. { complete } = check_pbi_complete(pbi_id)
5. if complete:
     prNumber = POST /repos/.../pulls
     set_pbi_pr(pbi_id, pr_url)
     enablePullRequestAutoMerge(prNumber, MERGE_METHOD: SQUASH)
6. on any HTTP/git failure → update_job_status('failed', error)

GITHUB_TOKEN-scope: repo voor private, public_repo voor public. Documenteer in worker-readme.

B.5 Repo-instellingen (handmatig, one-time)

• GitHub repo Settings → General → "Allow auto-merge" → aanvinken.
• Branch protection op main: required CI checks = ci, deploy-preview is niet required (kan skipped zijn door label).

---

Deel C — Interactie & demo-policy

C.1 Interactie deploy-controle ↔ auto-PR

Scenario	Preview-deploy	Prod-deploy bij merge
Worker maakt PR met code-changes (default)	✅ runt	✅ runt
Worker maakt PR met skip-deploy (manueel toegevoegd)	❌ skipped	✅ runt
Worker maakt PR met enkel docs-changes (path-filter)	❌ skipped	❌ skipped
User voegt force-deploy toe aan doc-only PR	✅ runt	✅ runt (path-filter) of ❌ (doc-only push)

Auto-merge wacht op required CI checks. deploy-preview mag skipped zijn — branch protection markeert hem niet als required.

C.2 Demo-policy

Auto-PR-flow draait op de worker, niet vanuit de webapp. Geen demo-sessie kan deze code triggeren — geen extra proxy.ts of session.isDemo-guards nodig. Wel: check_pbi_complete MCP-call moet requireWriteAccess doen (consistent met andere write-MCP-tools), zodat demo-tokens hem niet kunnen aanroepen.

---

---

Deel D — Sync-tab op Idea-detail (zicht op voortgang)

D.1 Wat bestaat al

• model StoryLog (prisma/schema.prisma:251) met types IMPLEMENTATION_PLAN | TEST_RESULT | COMMIT, plus commit_hash, commit_message, metadata. Dit is de activiteitenlog.
• MCP-tools log_implementation, log_commit, log_test_result schrijven naar deze tabel.
• UI-component components/shared/story-log.tsx rendert StoryLogEntry[] met type-styling.
• Story.status, ClaudeJob.pushed_at/branch/pr_url, Pbi.pr_url/pr_merged_at zijn al gevuld door bestaande flows.

Geen nieuwe tabellen, geen migraties.

D.2 Nieuwe tab op /ideas/[id]

Voeg vijfde tab Sync toe (naast Idee · Grill · Plan · Timeline) op Idea-detail-page. Alleen zichtbaar als Idea.status === 'PLANNED' en pbi_id gevuld.

Layout per tab-content:

• Header: PBI-link + pr_url + pr_merged_at als badge.
• Per Story (volgorde uit PBI): collapsible card met:
  • Story-header: code · titel · status-badge.
  • Job-rij: voor elke ClaudeJob (kind=TASK_IMPLEMENTATION) gelinkt aan een Task van deze Story → status, branch, pushed_at, pr_url. Toont "geen job" als nog niets gequeued.
  • Activity-log: <StoryLog logs={logs} repoUrl={product.repo_url} /> — bestaande component, ongewijzigd.

D.3 Server-laag

Nieuwe loader in app/(app)/ideas/[id]/page.tsx (of nieuw sync-tab-server.ts):

async function loadIdeaSyncData(ideaId: string, userId: string) {
  // Auth-scope: idea.user_id === userId (M12-keuze 2)
  return prisma.idea.findFirst({
    where: { id: ideaId, user_id: userId },
    include: {
      pbi: {
        include: {
          stories: {
            orderBy: { sort_order: 'asc' },
            include: {
              tasks: { include: { claude_jobs: true } },
              logs: { orderBy: { created_at: 'desc' } },
            },
          },
        },
      },
    },
  })
}

Server-only. Nooit importeren in client component (zie hardstop *-server.ts regel).

D.4 Realtime refresh

Sync-tab abonneert op bestaande SSE-streams:

• app/api/realtime/solo/route.ts — JobPayload voor job-status-updates (al uitgebreid met kind en idea_id per Deel B).
• app/api/realtime/notifications/route.ts — voor StoryLog-inserts; als story_logs nog geen pg_notify-trigger heeft, voeg er een toe (nieuwe migratie, payload {op: 'INSERT', entity: 'story_log', id, story_id}).

Op event → router.refresh() of revalidate van Sync-tab data.

D.5 PBI-33 als live testgeval

PBI-33 is nu in TODO + gequeued als ClaudeJobs (gebruiker bevestigt: "taken op TODO gezet en claude-job aangemaakt"). Verwacht gedrag zodra deze sprint live is:

Moment	Sync-tab toont
Job QUEUED	"Wachtend op worker"
Job RUNNING	Status RUNNING + log-entry IMPLEMENTATION_PLAN
Worker commit	log-entry COMMIT (hash + message)
Worker test	log-entry TEST_RESULT (status)
Worker push (Deel B AC 1)	branch + pushed_at zichtbaar
Laatste story → PR	PBI.pr_url zichtbaar
Auto-merge	PBI.pr_merged_at zichtbaar

Als één van deze niet verschijnt: bug in MCP-tool of worker (niet in sync-tab zelf).

---

Bestanden

Wijziging	Pad
Edit	vercel.json
Edit	.github/workflows/ci.yml
Nieuw	docs/runbooks/deploy-control.md
Edit	CLAUDE.md (verwijzing toevoegen)
Nieuw (mcp-repo)	src/tools/check-pbi-complete.ts
Edit (mcp-repo)	src/tools/update-job-status.ts (pushed_at)
Edit	actions/jobs.ts (optioneel: record-pushed-at)
Edit	Worker-script (post-story-hook + PR-aanmaak)
Doc	docs/runbooks/auto-pr-flow.md (worker-flow)
Nieuw	app/(app)/ideas/[id]/sync-tab-server.ts
Nieuw	components/ideas/idea-sync-tab.tsx
Edit	app/(app)/ideas/[id]/page.tsx (5e tab toevoegen)
Migratie	prisma/migrations/<ts>_story_logs_notify/migration.sql (pg_notify-trigger op story_logs)
Edit	app/api/realtime/notifications/route.ts (story_log-payload doorlaten)
GitHub (extern)	Labels skip-deploy, force-deploy aanmaken
GitHub (extern)	Repo Settings → "Allow auto-merge" aan
Vercel-dashboard	git.deploymentEnabled: false actief verifiëren

Implementatievolgorde

1. Deel A — Deploy-controle

   1. vercel.json aanpassen
   2. ci.yml uitbreiden (path-filter, labels, dispatch)
   3. Labels op GitHub aanmaken
   4. Runbook + CLAUDE.md-verwijzing
   5. Test-PR voor elk scenario (zie Verificatie)

2. Deel D — Sync-tab (kan parallel met B; alleen DB-reads + UI)

   1. loadIdeaSyncData server-loader
   2. idea-sync-tab.tsx component met <StoryLog>-hergebruik
   3. 5e tab in app/(app)/ideas/[id]/page.tsx
   4. pg_notify-trigger op story_logs + SSE-route uitbreiden
   5. Live test op PBI-33 (sprint loopt al — check of activity verschijnt zodra worker logs schrijft)

3. Deel B — Auto-PR

   1. MCP check_pbi_complete + update_job_status(pushed_at) PR (parallel-repo, schema-drift-watchdog groen)
   2. Worker-hook: push na done, PR + auto-merge bij complete
   3. Repo-instelling "Allow auto-merge" aan
   4. End-to-end smoke met één test-PBI

Verificatie

Lokaal:

npm run lint && npm test && npm run build

Workflow-syntax:

gh workflow view ci.yml

End-to-end deploy-controle:

1. Doc-only PR → deploy-preview skipped.
2. Doc-only PR + force-deploy → deploy-preview runt.
3. Code-PR + skip-deploy → deploy-preview skipped.
4. Code-PR zonder labels → deploy-preview runt.
5. Push naar main met code-change → deploy-production runt.
6. Push naar main doc-only → deploy-production skipped.
7. workflow_dispatch target=production → manuele prod.
8. Vercel dashboard → geen auto-deploy bij geforceerde test-push.

End-to-end auto-PR:

9. Maak een test-PBI met 1 story + 1 task.
10. Worker draait → na done: pushed_at gevuld, branch op origin zichtbaar.
11. check_pbi_complete → complete: true.
12. PR verschijnt op GitHub met titel = PBI-naam, body = story-list.
13. Auto-merge actief; CI groen → squash-merge.
14. mark_pbi_pr_merged getriggerd door pull_request: closed-webhook (al bestaand) → Pbi.pr_merged_at gevuld.
15. Push-event op main → deploy-production runt (path-filter ja).
16. Failure-test: revoke GITHUB_TOKEN tijdelijk → push faalt → update_job_status('failed') met error; geen PR aangemaakt.

Out-of-scope (v1)

• UI-toggle voor auto_pr per product (veld bestaat, geen UI-wiring).
• GitHub App-installatie (per-repo tokens, scopes-finetuning).
• Multi-repo PBI's (huidig ontwerp: één repo_url per PBI).
• Force-push / non-fast-forward retry-flow.
• Notificaties (Slack, e-mail) bij merge of CI-failure.
• Rollback-flow bij gemergende regressie.
• Migratie naar vercel.ts (knowledge-update beveelt het aan; later).
• Auto-skip preview-deploy specifiek voor worker-PRs op basis van product-instelling.