create-agentic-pdlc 2.3.0 → 3.0.0

package/{.agentic-pdlc/templates → templates}/.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');
@@ -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,7 +416,6 @@ 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) {
@@ -373,7 +496,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;

package/templates/.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/templates/.github/workflows/pdlc-health-check.yml

@@ -27,7 +27,7 @@ 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: |

package/templates/.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/templates/.github/workflows/project-automation.yml

@@ -27,13 +27,13 @@ jobs:
     if: github.event_name == 'issues' && github.event.action == 'labeled'
     runs-on: ubuntu-latest
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Detect Label and Move Issue
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const labelName = context.payload.label.name;
             let targetStatusId = null;
@@ -51,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) {
@@ -91,13 +88,13 @@ jobs:
       contains(github.event.issue.labels.*.name, 'stage:detailing')
     runs-on: ubuntu-latest
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Check spec markers and swap labels
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const body = context.payload.issue.body ?? '';
             if (!body.includes('## Acceptance Criteria') || !body.includes('## Files to modify')) return;
@@ -109,6 +106,42 @@ jobs:
             await github.rest.issues.removeLabel({ owner, repo, issue_number, name: 'stage:detailing' }).catch(() => {});
             console.log(`Issue #${issue_number} auto-moved to stage:approval`);
 
+  # 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
@@ -116,10 +149,10 @@ jobs:
   #   runs-on: ubuntu-latest
   #   steps:
   #     - name: Move issue to Idea
-  #       if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-  #       uses: actions/github-script@v7
+  #       if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+  #       uses: actions/github-script@v8
   #       with:
-  #         github-token: ${{ env.PROJECT_PAT }}
+  #         github-token: ${{ env.PROJECT_TOKEN }}
   #         script: |
   #           const { issue: { number, node_id } } = context.payload;
   #           const { addProjectV2ItemById: { item } } = await github.graphql(`
@@ -143,13 +176,13 @@ jobs:
     if: github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'reopened')
     runs-on: ubuntu-latest
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move linked issue to Testing
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const prNumber = context.payload.pull_request.number;
             const { owner, repo } = context.repo;
@@ -197,13 +230,13 @@ jobs:
     if: github.event_name == 'pull_request' && github.event.action == 'labeled' && github.event.label.name == 'qa:approved'
     runs-on: ubuntu-latest
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move linked issue to Code Review / PR
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const prNumber = context.payload.pull_request.number;
             const { owner, repo } = context.repo;
@@ -229,6 +262,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 {
@@ -242,13 +278,13 @@ jobs:
     if: github.event_name == 'pull_request_review' && github.event.review.state == 'approved'
     runs-on: ubuntu-latest
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Swap PR labels
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const prNumber = context.payload.pull_request.number;
             const { owner, repo } = context.repo;
@@ -261,13 +297,13 @@ jobs:
     if: github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged == true
     runs-on: ubuntu-latest
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move issue to Production
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const prNumber = context.payload.pull_request.number;
             const { owner, repo } = context.repo;
@@ -293,6 +329,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:approval')) {
+                  await github.rest.issues.removeLabel({ owner, repo, issue_number: n, name: 'stage:approval' }).catch(() => {});
+                }
                 console.log(`Issue #${n} → Production`);
               }
             } else {
@@ -305,7 +344,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Remove transient labels
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -314,7 +353,7 @@ jobs:
             const toRemove = [
               'stage:brainstorming', 'stage:detailing',
               'stage:approval', 'stage:development', 'stage:testing',
-              'agent:working', 'qa:needs-work', 'pr:in-review', 'jules'
+              'qa:needs-work', 'pr:in-review', 'jules'
             ];
             for (const label of toRemove) {
               await github.rest.issues.removeLabel({ owner, repo, issue_number, name: label }).catch(() => {});

package/templates/.github/workflows/qa-agent.yml

@@ -14,9 +14,9 @@ jobs:
     name: AC Coverage Verification (GitHub Models)
     runs-on: ubuntu-latest
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5.0.1
         with:
           fetch-depth: 0
 
@@ -31,7 +31,7 @@ jobs:
           HEAD="${{ github.event.pull_request.head.sha }}"
 
           # Get PR diff (truncated to 8000 chars to stay within context limits)
-          DIFF=$(git diff "$BASE" "$HEAD" | head -c 64000)
+          DIFF=$(git diff "$BASE" "$HEAD" | head -c 8000)
 
           # Extract linked issues from PR body
           PR_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body // ""')
@@ -51,31 +51,45 @@ jobs:
           fi
 
           # Serialize prompt as JSON string and call GitHub Models API (30s timeout)
-          PROMPT_JSON=$(printf '%s' "You are a senior QA engineer. Review whether this PR diff satisfies the Acceptance Criteria below.\n\nACCEPTANCE CRITERIA:\n${AC_CONTEXT}\n\nPR DIFF:\n${DIFF}\n\nFirst line of your response must be exactly one word: PASS or FAIL. Second line: brief explanation (max 3 sentences)." | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')
+          PROMPT_JSON=$(printf '%s' "You are an adversarial product tester. Your mission is to find what the Acceptance Criteria do NOT cover — undefined edge cases, ambiguous states, missing user scenarios. Do NOT review code quality, file structure, or technical consistency.\n\nACCEPTANCE CRITERIA:\n${AC_CONTEXT}\n\nPR DIFF:\n${DIFF}\n\nRespond in exactly 3 lines (do NOT wrap your response in markdown code blocks or any other formatting):\nLine 1: PASS or FAIL (PASS if the PR diff fully satisfies the stated Acceptance Criteria, FAIL if it falls short of covering them)\nLine 2: Gaps: [one-line summary of AC gaps found, or \"none\"]\nLine 3: Not covered: [AC refs where diff falls short, or \"all covered\"]" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')
 
-          RESPONSE=$(curl -sf -X POST \
-            "https://models.github.ai/inference/chat/completions" \
-            -H "Authorization: Bearer ${GITHUB_TOKEN}" \
-            -H "Content-Type: application/json" \
-            -d "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":${PROMPT_JSON}}]}" \
-            --max-time 30 || echo "API_ERROR")
+          RESPONSE="API_ERROR"
+          for attempt in 1 2 3; do
+            RESULT=$(curl -s -X POST \
+              "https://models.github.ai/inference/chat/completions" \
+              -H "Authorization: Bearer ${GITHUB_TOKEN}" \
+              -H "Content-Type: application/json" \
+              -d "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":${PROMPT_JSON}}]}" \
+              -w "\n__HTTP_STATUS__:%{http_code}" \
+              --max-time 45 2>/dev/null)
+            HTTP_STATUS=$(echo "$RESULT" | grep -o '__HTTP_STATUS__:[0-9]*' | cut -d: -f2)
+            BODY=$(echo "$RESULT" | sed 's/__HTTP_STATUS__:[0-9]*$//')
+            echo "Attempt $attempt: HTTP $HTTP_STATUS"
+            if [ "$HTTP_STATUS" = "200" ]; then RESPONSE="$BODY"; break; fi
+            [ $attempt -lt 3 ] && sleep 20
+          done
 
           if [ "$RESPONSE" = "API_ERROR" ]; then
-            GH_TOKEN="$PROJECT_PAT" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=infra:qa-broken'
+            GH_TOKEN="$PROJECT_TOKEN" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=infra:qa-broken'
             gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not reach GitHub Models API. Manual review required."
-            exit 0
+            exit 1
           fi
 
-          VERDICT=$(echo "$RESPONSE" | python3 -c 'import json,sys,re; d=json.load(sys.stdin); t=d.get("choices",[{}])[0].get("message",{}).get("content","").strip(); first=t.split("\n")[0].upper() if t else ""; print("FAIL" if re.search(r"\bFAIL\b",first) else "PASS" if re.search(r"\bPASS\b",first) else "API_ERROR")')
+          VERDICT=$(echo "$RESPONSE" | python3 -c 'import json,sys,re; d=json.load(sys.stdin); t=d.get("choices",[{}])[0].get("message",{}).get("content","").strip(); lines=[l for l in t.split("\n") if not l.strip().startswith("```")]; first=lines[0].upper() if lines else ""; print("FAIL" if re.search(r"\bFAIL\b",first) else "PASS" if re.search(r"\bPASS\b",first) else "API_ERROR")')
           EXPLANATION=$(echo "$RESPONSE" | python3 -c 'import json,sys; d=json.load(sys.stdin); t=d.get("choices",[{}])[0].get("message",{}).get("content","").strip(); lines=t.split("\n",1); print(lines[1].strip() if len(lines)>1 else "")')
 
           if echo "$VERDICT" | grep -q "^PASS"; then
-            GH_TOKEN="$PROJECT_PAT" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=qa:approved'
-            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** AC coverage verified. ${EXPLANATION}"
+            GH_TOKEN="$PROJECT_TOKEN" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=qa:approved'
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** PASS
+
+${EXPLANATION}"
           elif echo "$VERDICT" | grep -q "^FAIL"; then
-            GH_TOKEN="$PROJECT_PAT" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=qa:needs-work'
-            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** AC coverage insufficient. ${EXPLANATION}"
+            GH_TOKEN="$PROJECT_TOKEN" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=qa:needs-work'
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** FAIL
+
+${EXPLANATION}"
           else
-            GH_TOKEN="$PROJECT_PAT" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=infra:qa-broken'
+            GH_TOKEN="$PROJECT_TOKEN" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=infra:qa-broken'
             gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not parse GitHub Models response. Manual review required."
+            exit 1
           fi

package/templates/.github/workflows/qa-gate.yml

@@ -0,0 +1,51 @@
+name: QA Gate
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  qa-gate:
+    name: QA Gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check QA status label
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+          REPO="${{ github.repository }}"
+
+          PR_LABELS=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json labels --jq '.labels[].name')
+
+          if echo "$PR_LABELS" | grep -qx "hotfix"; then
+            echo "✅ QA Gate: hotfix label — bypassed."
+            exit 0
+          fi
+
+          if echo "$PR_LABELS" | grep -qx "human-approved"; then
+            echo "✅ QA Gate: human-approved label — manual QA sign-off, bypassed."
+            exit 0
+          fi
+
+          if echo "$PR_LABELS" | grep -qx "qa:approved"; then
+            echo "✅ QA Gate: qa:approved — merge allowed."
+            exit 0
+          fi
+
+          if echo "$PR_LABELS" | grep -qx "infra:qa-broken"; then
+            echo "❌ QA Gate: infra:qa-broken — GitHub Models API unreachable. Manual QA review required before merge."
+            exit 1
+          fi
+
+          if echo "$PR_LABELS" | grep -qx "qa:needs-work"; then
+            echo "❌ QA Gate: qa:needs-work — acceptance criteria not fully met. Fix required before merge."
+            exit 1
+          fi
+
+          echo "❌ QA Gate: no QA label found — AC Coverage Verification has not completed. Wait for the check to finish."
+          exit 1