create-agentic-pdlc 2.2.1 → 2.4.0

package/.github/workflows/agentic-metrics.yml

@@ -9,15 +9,20 @@ permissions:
   contents: write
   issues: write
 
+env:
+  AGENTIC_PULSE_REVIEWERS: |
+    code_reviewer=gemini-code-assist[bot]
+    qa_agent=github-actions[bot]
+
 jobs:
   generate-pulse:
     name: Generate Weekly Agentic Pulse
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5.0.1
 
       - name: Collect Stage Residence Time
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const fs = require('fs');
@@ -25,7 +30,7 @@ jobs:
             const { owner, repo } = context.repo;
             const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
             const STAGE_LABELS = new Set([
-              'stage:exploration', 'stage:brainstorming', 'stage:detailing',
+              'stage:brainstorming', 'stage:detailing',
               'stage:approval', 'stage:development', 'stage:testing'
             ]);
 
@@ -104,13 +109,26 @@ jobs:
           git push
 
       - name: Collect PR and Issue Insights
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const fs = require('fs');
             const { owner, repo } = context.repo;
             const weekKey = process.env.WEEK_KEY;
 
+            // ── Preload stage:detailing times for stage correlation ──────────
+            const detailingByIssue = {};
+            const jsonlPath = `.agentic-pdlc/metrics/raw/${weekKey}.jsonl`;
+            if (fs.existsSync(jsonlPath)) {
+              const rawLines = fs.readFileSync(jsonlPath, 'utf8').trim().split('\n').filter(Boolean);
+              for (const line of rawLines) {
+                const r = JSON.parse(line);
+                if (r.stage === 'stage:detailing') {
+                  detailingByIssue[r.issueNumber] = round1((detailingByIssue[r.issueNumber] || 0) + r.durationDays);
+                }
+              }
+            }
+
             // ── Helper ──────────────────────────────────────────────────────
             function daysSince(isoStr) {
               return (Date.now() - new Date(isoStr).getTime()) / 864e5;
@@ -138,6 +156,22 @@ jobs:
             // ── Signal collection ───────────────────────────────────────────
             const signals = [];
 
+            // ── Review actor map (from AGENTIC_PULSE_REVIEWERS env var) ─────
+            const actorMap = {}; // login → role
+            const reviewersEnv = (process.env.AGENTIC_PULSE_REVIEWERS || '').trim();
+            if (reviewersEnv) {
+              for (const line of reviewersEnv.split('\n')) {
+                const eq = line.indexOf('=');
+                if (eq < 0) continue;
+                const role = line.slice(0, eq).trim();
+                const logins = line.slice(eq + 1).trim();
+                for (const login of logins.split(',').map(l => l.trim()).filter(Boolean)) {
+                  actorMap[login] = role;
+                }
+              }
+            }
+            const taxonomyEnabled = Object.keys(actorMap).length > 0;
+
             // 1. Orphan issues: open >14 days with no linked PR
             const closeRe = /(?:closes?|fixes?|resolves?)\s+#(\d+)/gi;
             const openIssues = await github.paginate(github.rest.issues.listForRepo, {
@@ -223,29 +257,68 @@ jobs:
               }
             }
 
-            // 3. Rework rate: commits per PR — single push session = first-shot
+            // 3. Rework rate with actor taxonomy (if AGENTIC_PULSE_REVIEWERS configured)
             const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
             const weekMerged = recentPRs.filter(pr => pr.merged_at && new Date(pr.merged_at) > weekAgo);
 
             if (weekMerged.length > 0) {
               let firstShots = 0;
+              const reworkByRole = {};
+              const reworkDetails = []; // { pr_number, issue_number } for stage correlation
+              const issueRe = /(?:closes?|fixes?|resolves?)\s+#(\d+)/i;
+
               for (const pr of weekMerged.slice(0, 10)) {
                 try {
                   const commits = await github.rest.pulls.listCommits({
                     owner, repo, pull_number: pr.number, per_page: 100
                   });
-                  const times = commits.data.map(c => new Date(c.commit.committer.date).getTime()).sort();
+                  const times = commits.data
+                    .map(c => new Date(c.commit.committer.date).getTime())
+                    .sort((a, b) => a - b);
+
                   let sessions = 1;
                   for (let i = 1; i < times.length; i++) {
                     if (times[i] - times[i-1] > 10 * 60 * 1000) sessions++;
                   }
-                  if (sessions === 1) firstShots++;
+
+                  if (sessions === 1) { firstShots++; continue; }
+
+                  if (!taxonomyEnabled) continue;
+
+                  let reviewTriggered = false;
+                  try {
+                    const reviews = await github.rest.pulls.listReviews({
+                      owner, repo, pull_number: pr.number, per_page: 100
+                    });
+                    const attributedRoles = new Set();
+                    for (const review of reviews.data) {
+                      if (!review.user) continue;
+                      const role = actorMap[review.user.login];
+                      if (!role || review.state === 'APPROVED' || attributedRoles.has(role)) continue;
+                      const reviewTime = new Date(review.submitted_at).getTime();
+                      if (times.some(t => t > reviewTime)) {
+                        reworkByRole[role] = (reworkByRole[role] || 0) + 1;
+                        reviewTriggered = true;
+                        attributedRoles.add(role);
+                        if (!reworkDetails.some(d => d.pr_number === pr.number)) {
+                          const m = issueRe.exec(pr.body || '');
+                          if (m) reworkDetails.push({ pr_number: pr.number, issue_number: parseInt(m[1]) });
+                        }
+                      }
+                    }
+                  } catch(e) { /* reviews not accessible — skip taxonomy for this PR */ }
+
+                  if (!reviewTriggered) {
+                    reworkByRole.self_correction = (reworkByRole.self_correction || 0) + 1;
+                  }
+
                 } catch (e) { /* skip if commits not accessible */ }
               }
+
               const total = Math.min(weekMerged.length, 10);
               const pct = Math.round(firstShots / total * 100);
+              const reworkCount = total - firstShots;
 
-              // Detect if repo uses an agent label (jules, sweep, codex, etc.)
               const agentLabels = new Set(['jules', 'sweep', 'codex', 'copilot']);
               const usesAgent = weekMerged.some(pr =>
                 (pr.labels || []).some(l => agentLabels.has(l.name.toLowerCase()))
@@ -253,27 +326,78 @@ jobs:
               const subject = usesAgent ? 'Agent first-shot rate' : 'PRs sem rework';
               const verb = usesAgent ? 'acertaram de primeira' : 'foram mergeados sem rework';
 
-              if (pct >= 80) {
-                signals.push({
-                  level: 'green',
-                  emoji: '🟢',
-                  title: `**${subject}: ${pct}%**`,
-                  body: `${firstShots} de ${total} PRs ${verb} esta semana. ✅`
-                });
-              } else if (pct < 50) {
+              if (taxonomyEnabled && reworkCount > 0) {
+                const lines = [];
+                for (const [role, count] of Object.entries(reworkByRole).sort((a, b) => b[1] - a[1])) {
+                  const s = count > 1 ? 's' : '';
+                  if (role === 'code_reviewer')        lines.push(`   ↳ Code reviewer: **${count} PR${s}** → revisar DoD em stage:development`);
+                  else if (role === 'qa_agent')        lines.push(`   ↳ QA Agent: **${count} PR${s}** → spec com lacunas funcionais em stage:detailing`);
+                  else if (role === 'self_correction') lines.push(`   ↳ Self-correction: **${count} PR${s}** (causa não determinada automaticamente)`);
+                  else                                 lines.push(`   ↳ ${role}: **${count} PR${s}**`);
+                }
+
+                const reviewerRework = reworkByRole.code_reviewer || 0;
+                const level = reviewerRework >= Math.ceil(reworkCount * 0.8) ? 'red'
+                            : (reviewerRework >= Math.ceil(reworkCount * 0.5) || (reworkByRole.qa_agent || 0) > 0) ? 'yellow'
+                            : 'neutral';
+                const emoji = level === 'red' ? '🔴' : level === 'yellow' ? '🟡' : '🔵';
+
                 signals.push({
-                  level: 'yellow',
-                  emoji: '🟡',
-                  title: `**${subject}: ${pct}% — rework alto**`,
-                  body: `Apenas ${firstShots} de ${total} PRs sem commits extras.\n→ Specs incompletas ou mudanças de requisito durante implementação.`
+                  level,
+                  emoji,
+                  title: `**Rework: ${100 - pct}%** — ${reworkCount} de ${total} PRs tiveram commits extras`,
+                  body: lines.join('\n')
                 });
+
+                // ── Stage correlation ────────────────────────────────────────
+                if (reworkDetails.length > 0 && Object.keys(detailingByIssue).length > 0) {
+                  const reworkIssueNums = new Set(reworkDetails.map(d => d.issue_number));
+
+                  const reworkGroup = reworkDetails
+                    .map(d => detailingByIssue[d.issue_number])
+                    .filter(t => t !== undefined);
+
+                  const cleanGroup = weekMerged.slice(0, 10)
+                    .map(pr => { const m = issueRe.exec(pr.body || ''); return m ? parseInt(m[1]) : null; })
+                    .filter(n => n !== null && !reworkIssueNums.has(n))
+                    .map(n => detailingByIssue[n])
+                    .filter(t => t !== undefined);
+
+                  if (reworkGroup.length >= 3 && cleanGroup.length >= 3) {
+                    const avgRework = round1(reworkGroup.reduce((a, b) => a + b, 0) / reworkGroup.length);
+                    const avgClean  = round1(cleanGroup.reduce((a, b) => a + b, 0) / cleanGroup.length);
+                    if (avgRework < avgClean * 0.75) {
+                      signals.push({
+                        level: 'neutral',
+                        emoji: '💡',
+                        title: `**Stage correlation:** PRs com reviewer rework tiveram Detailing médio de ${avgRework}d vs ${avgClean}d (N=${reworkGroup.length} vs ${cleanGroup.length})`,
+                        body: '→ Specs rápidas correlacionam com mais rework de review'
+                      });
+                    }
+                  }
+                }
+
               } else {
-                signals.push({
-                  level: 'neutral',
-                  emoji: '🔵',
-                  title: `**${subject}: ${pct}%**`,
-                  body: `${firstShots} de ${total} PRs sem rework commits.`
-                });
+                // Taxonomy disabled or no rework — existing signal unchanged
+                if (pct >= 80) {
+                  signals.push({
+                    level: 'green', emoji: '🟢',
+                    title: `**${subject}: ${pct}%**`,
+                    body: `${firstShots} de ${total} PRs ${verb} esta semana. ✅`
+                  });
+                } else if (pct < 50) {
+                  signals.push({
+                    level: 'yellow', emoji: '🟡',
+                    title: `**${subject}: ${pct}% — rework alto**`,
+                    body: `Apenas ${firstShots} de ${total} PRs sem commits extras.\n→ Specs incompletas ou mudanças de requisito durante implementação.`
+                  });
+                } else {
+                  signals.push({
+                    level: 'neutral', emoji: '🔵',
+                    title: `**${subject}: ${pct}%**`,
+                    body: `${firstShots} de ${total} PRs sem rework commits.`
+                  });
+                }
               }
             }
 
@@ -292,12 +416,10 @@ jobs:
 
             // ── Stage Residence Time section (conditional) ──────────────────
             let stageSection = '';
-            const jsonlPath = `.agentic-pdlc/metrics/raw/${weekKey}.jsonl`;
             if (fs.existsSync(jsonlPath)) {
               const records = fs.readFileSync(jsonlPath, 'utf8').trim().split('\n').filter(Boolean).map(JSON.parse);
               if (records.length > 0) {
                 const STAGES = [
-                  ['stage:exploration',   'Exploration'],
                   ['stage:brainstorming', 'Brainstorming'],
                   ['stage:detailing',     'Detailing'],
                   ['stage:approval',      'Approval'],
@@ -311,11 +433,14 @@ jobs:
                 }
                 const avg = arr => arr.reduce((a, b) => a + b, 0) / arr.length;
 
-                let maxStage = null, maxDays = 0;
+                let maxStage = null, maxDays = -1;
                 const rows = [];
                 for (const [stage, label] of STAGES) {
                   const days = byStage[stage];
-                  if (!days) continue;
+                  if (!days) {
+                    rows.push(`| **${label}** | — | — |`);
+                    continue;
+                  }
                   const a = round1(avg(days));
                   rows.push(`| **${label}** | ${a}d | ${days.length} |`);
                   if (a > maxDays) { maxStage = label; maxDays = a; }
@@ -374,7 +499,7 @@ jobs:
             console.log(`Built pulse issue for ${weekKey} — ${signals.length} signals, ${reds} red, ${yellows} yellow`);
 
       - name: Create Weekly Pulse Issue
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const { owner, repo } = context.repo;
@@ -394,19 +519,27 @@ jobs:
               console.log(`Created label ${LABEL}`);
             }
 
-            // Close previous pulse issues
+            // Close previous pulse issues; upsert if same week already exists
             const prev = await github.rest.issues.listForRepo({
               owner, repo, labels: LABEL, state: 'open', per_page: 20
             });
+            let existingIssue = null;
             for (const issue of prev.data) {
-              if (issue.title !== title) {
+              if (issue.title === title) {
+                existingIssue = issue;
+                console.log(`Found existing pulse for ${title}: #${issue.number} — will update body`);
+              } else {
                 await github.rest.issues.update({ owner, repo, issue_number: issue.number, state: 'closed' });
                 console.log(`Closed previous pulse: #${issue.number}`);
               }
             }
 
-            // Create new pulse issue
-            const created = await github.rest.issues.create({
-              owner, repo, title, body, labels: [LABEL]
-            });
-            console.log(`✅ Created pulse issue: #${created.data.number} — ${title}`);
+            if (existingIssue) {
+              await github.rest.issues.update({ owner, repo, issue_number: existingIssue.number, body });
+              console.log(`✅ Updated pulse issue: #${existingIssue.number} — ${title}`);
+            } else {
+              const created = await github.rest.issues.create({
+                owner, repo, title, body, labels: [LABEL]
+              });
+              console.log(`✅ Created pulse issue: #${created.data.number} — ${title}`);
+            }

package/.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     name: Run tests and linters
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5.0.1
 
       - name: Setup environment
         run: echo "Replace this with your language/toolchain setup (e.g., actions/setup-node)"

package/.github/workflows/npm-publish.yml

@@ -14,10 +14,10 @@ jobs:
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5.0.1
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6.4.0
         with:
           node-version: '24'
           registry-url: 'https://registry.npmjs.org'

package/.github/workflows/pdlc-health-check.yml

@@ -8,7 +8,6 @@ on:
 env:
   PROJECT_ID: "PVT_kwHODpFFL84BXg7h"
   STATUS_FIELD_ID: "PVTSSF_lAHODpFFL84BXg7hzhStRHI"
-  STATUS_EXPLORATION: "96ac537d"
   STATUS_BRAINSTORMING: "8eb07c5b"
   STATUS_DETAILING: "9f6ce70e"
   STATUS_APPROVAL: "31bf4610"
@@ -28,14 +27,13 @@ jobs:
     steps:
       - name: Validate Board Configuration
         if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const projectId = process.env.PROJECT_ID;
             const statusFieldId = process.env.STATUS_FIELD_ID;
             const envVars = {
-              'STATUS_EXPLORATION': process.env.STATUS_EXPLORATION,
               'STATUS_BRAINSTORMING': process.env.STATUS_BRAINSTORMING,
               'STATUS_DETAILING': process.env.STATUS_DETAILING,
               'STATUS_APPROVAL': process.env.STATUS_APPROVAL,

package/.github/workflows/pdlc-stage-gate.yml

@@ -37,12 +37,12 @@ jobs:
 
           for NUM in $ISSUE_NUMS; do
             LABELS=$(gh issue view "$NUM" --repo "$REPO" --json labels --jq '[.labels[].name] | join(" ")' 2>/dev/null || echo "")
-            if echo "$LABELS" | grep -qw "stage:approval" || echo "$LABELS" | grep -qw "spec:approved" || echo "$LABELS" | grep -qw "stage:development"; then
+            if echo "$LABELS" | grep -qw "stage:approval" || echo "$LABELS" | grep -qw "spec:approved" || echo "$LABELS" | grep -qw "stage:development" || echo "$LABELS" | grep -qw "stage:testing" || echo "$LABELS" | grep -qw "human-approved"; then
               echo "✅ Issue #$NUM approved"
             else
               STAGE=$(echo "$LABELS" | tr ' ' '\n' | grep "^stage:" | head -1 || echo "none")
               echo "❌ Issue #$NUM missing approval (current: $STAGE)"
-              echo "   Required: stage:approval OR spec:approved OR stage:development label on the issue."
+              echo "   Required: stage:approval OR spec:approved OR stage:development OR stage:testing OR human-approved label on the issue."
               echo "   Emergency bypass: add 'hotfix' label to this PR."
               exit 1
             fi

package/.github/workflows/project-automation.yml

@@ -6,13 +6,12 @@ on:
   pull_request_review:
     types: [submitted]
   issues:
-    types: [labeled]
+    types: [labeled, closed]
 
 env:
   PROJECT_ID: "PVT_kwHODpFFL84BXg7h"
   STATUS_FIELD_ID: "PVTSSF_lAHODpFFL84BXg7hzhStRHI"
   STATUS_IDEA: "bb6e5a20"
-  STATUS_EXPLORATION: "96ac537d"
   STATUS_BRAINSTORMING: "8eb07c5b"
   STATUS_DETAILING: "9f6ce70e"
   STATUS_APPROVAL: "31bf4610"
@@ -32,7 +31,7 @@ jobs:
     steps:
       - name: Detect Label and Move Issue
         if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |
@@ -40,10 +39,7 @@ jobs:
             let targetStatusId = null;
             let stageName = null;
 
-            if (labelName === 'stage:exploration') {
-              targetStatusId = process.env.STATUS_EXPLORATION;
-              stageName = 'Exploration';
-            } else if (labelName === 'stage:brainstorming') {
+            if (labelName === 'stage:brainstorming') {
               targetStatusId = process.env.STATUS_BRAINSTORMING;
               stageName = 'Brainstorming';
             } else if (labelName === 'stage:detailing') {
@@ -55,9 +51,6 @@ jobs:
             } else if (labelName === 'stage:development') {
               targetStatusId = process.env.STATUS_DEVELOPMENT;
               stageName = 'Development';
-            } else if (labelName === 'stage:testing') {
-              targetStatusId = process.env.STATUS_TESTING;
-              stageName = 'Testing';
             }
 
             if (!targetStatusId) {
@@ -87,6 +80,42 @@ jobs:
             await moveItem(node_id, targetStatusId);
             console.log(`Issue #${number} moved to ${stageName}`);
 
+  # human-approved on issue → qa:approved on linked open PRs
+  handle-human-approved:
+    name: human-approved → qa:approved on linked PRs
+    if: github.event_name == 'issues' && github.event.action == 'labeled' && github.event.label.name == 'human-approved'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Add qa:approved to linked open PRs
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { owner, repo } = context.repo;
+            const issueNumber = context.payload.issue.number;
+            const pattern = new RegExp(`(?:Closes?|Fixes?|Resolves?)\\s+#${issueNumber}\\b`, 'i');
+
+            const prs = await github.paginate(github.rest.pulls.list, {
+              owner, repo, state: 'open', per_page: 100
+            });
+
+            const linked = prs.filter(pr => pattern.test(pr.body ?? ''));
+
+            if (linked.length === 0) {
+              console.log(`No open PRs linking issue #${issueNumber}. Exiting.`);
+              return;
+            }
+
+            for (const pr of linked) {
+              await github.rest.issues.addLabels({
+                owner, repo, issue_number: pr.number, labels: ['qa:approved']
+              }).catch(() => {});
+              console.log(`PR #${pr.number} → qa:approved`);
+            }
+
   # OPTIONAL: Uncomment to enable architecture-violation → Idea
   # move-violation-to-board:
   #   name: architecture-violation → 💡 Idea
@@ -95,7 +124,7 @@ jobs:
   #   steps:
   #     - name: Move issue to Idea
   #       if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-  #       uses: actions/github-script@v7
+  #       uses: actions/github-script@v8
   #       with:
   #         github-token: ${{ env.PROJECT_TOKEN }}
   #         script: |
@@ -125,7 +154,7 @@ jobs:
     steps:
       - name: Move linked issue to Testing
         if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |
@@ -156,11 +185,17 @@ jobs:
                 });
             };
 
+            const stageLabelsToRemove = ['stage:development', 'stage:brainstorming', 'stage:detailing', 'jules'];
+
             if (linkedIssues.length > 0) {
               for (const n of linkedIssues) {
                 const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
                 await moveItem(issue.node_id);
-                console.log(`Issue #${n} → Testing`);
+                for (const label of stageLabelsToRemove) {
+                  await github.rest.issues.removeLabel({ owner, repo, issue_number: n, name: label }).catch(() => {});
+                }
+                await github.rest.issues.addLabels({ owner, repo, issue_number: n, labels: ['stage:testing'] }).catch(() => {});
+                console.log(`Issue #${n} → Testing (labels updated)`);
               }
             } else {
               await moveItem(pr.node_id);
@@ -179,7 +214,7 @@ jobs:
     steps:
       - name: Move linked issue to Code Review / PR
         if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |
@@ -213,6 +248,9 @@ jobs:
               for (const n of linkedIssues) {
                 const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
                 await moveItem(issue.node_id);
+                if (issue.labels?.some(l => l.name === 'stage:testing')) {
+                  await github.rest.issues.removeLabel({ owner, repo, issue_number: n, name: 'stage:testing' }).catch(() => {});
+                }
                 console.log(`Issue #${n} → Code Review / PR`);
               }
             } else {
@@ -230,7 +268,7 @@ jobs:
     steps:
       - name: Swap PR labels
         if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |
@@ -249,7 +287,7 @@ jobs:
     steps:
       - name: Move issue to Production
         if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |
@@ -277,8 +315,33 @@ jobs:
               for (const n of linkedIssues) {
                 const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
                 await moveItem(issue.node_id);
+                if (issue.labels?.some(l => l.name === 'stage:approval')) {
+                  await github.rest.issues.removeLabel({ owner, repo, issue_number: n, name: 'stage:approval' }).catch(() => {});
+                }
                 console.log(`Issue #${n} → Production`);
               }
             } else {
               await moveItem(pr.node_id);
             }
+
+  cleanup-labels-on-close:
+    name: Issue closed → strip stage/agent labels
+    if: github.event_name == 'issues' && github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Remove transient labels
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.issue.number;
+            const toRemove = [
+              'stage:brainstorming', 'stage:detailing',
+              'stage:approval', 'stage:development', 'stage:testing',
+              'qa:needs-work', 'pr:in-review', 'jules'
+            ];
+            for (const label of toRemove) {
+              await github.rest.issues.removeLabel({ owner, repo, issue_number, name: label }).catch(() => {});
+            }
+            console.log(`Issue #${issue_number} labels cleaned up`);