create-agentic-pdlc 2.1.6 → 2.2.1

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

@@ -6,22 +6,123 @@ on:
 permissions:
   pull-requests: write
   contents: read
+  issues: read
+  models: read
 
 jobs:
   qa:
-    name: Run AI QA Agent
+    name: AC Coverage Verification (GitHub Models)
     runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+      PROJECT_ID: "PVT_kwHODpFFL84BXg7h"
+      STATUS_FIELD_ID: "PVTSSF_lAHODpFFL84BXg7hzhStRHI"
+      STATUS_CODE_REVIEW_PR: "86ca9720"
     steps:
       - uses: actions/checkout@v4
-      - name: Execute QA Tests
-        run: |
-          echo "Run your QA Agent here."
-          echo "This could be QAWolf, a custom LLM script, or a secondary agent."
-          echo "If tests pass: gh pr edit $PR_URL --add-label 'qa:pass'"
-          echo "If tests fail: gh pr edit $PR_URL --add-label 'qa:fail'"
-          
-          # Example success:
-          # gh pr edit ${{ github.event.pull_request.html_url }} --add-label "qa:pass"
+        with:
+          fetch-depth: 0
+
+      - name: Verify AC Coverage via GitHub Models
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_URL: ${{ github.event.pull_request.html_url }}
+        run: |
+          set -e
+
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+          BASE="${{ github.event.pull_request.base.sha }}"
+          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)
+
+          # Extract linked issues from PR body
+          PR_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body // ""')
+          ISSUE_NUMS=$(echo "$PR_BODY" | grep -oiE '(Closes?|Fixes?|Resolves?)\s+#([0-9]+)' | grep -oE '[0-9]+' || true)
+
+          # Build acceptance criteria context
+          AC_CONTEXT=""
+          if [ -n "$ISSUE_NUMS" ]; then
+            for NUM in $ISSUE_NUMS; do
+              ISSUE_BODY=$(gh issue view "$NUM" --json body --jq '.body // ""' 2>/dev/null || echo "")
+              AC_CONTEXT="${AC_CONTEXT}\\n\\n--- Issue #${NUM} ---\\n${ISSUE_BODY}"
+            done
+          fi
+
+          if [ -z "$AC_CONTEXT" ]; then
+            AC_CONTEXT="No linked issue found. Evaluate if the PR description is self-contained."
+          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()))')
+
+          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")
+
+          if [ "$RESPONSE" = "API_ERROR" ]; then
+            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not reach GitHub Models API. Manual review required."
+            exit 0
+          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")')
+          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 pr edit "$PR_NUMBER" --add-label "qa:approved"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** AC coverage verified. ${EXPLANATION}"
+          elif echo "$VERDICT" | grep -q "^FAIL"; then
+            gh pr edit "$PR_NUMBER" --add-label "qa:needs-work"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** AC coverage insufficient. ${EXPLANATION}"
+          else
+            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not parse GitHub Models response. Manual review required."
+          fi
+
+      - name: Move board card to Code Review on qa:approved
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const { owner, repo } = context.repo;
+
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+            if (!pr.labels.some(l => l.name === 'qa:approved')) {
+              console.log('qa:approved not on PR — skipping board move');
+              return;
+            }
+
+            const body = pr.body ?? '';
+            const linkedIssues = [...body.matchAll(/(?:Closes?|Fixes?|Resolves?)\s+#(\d+)/gi)]
+              .map(m => parseInt(m[1]));
+
+            const moveItem = async (nodeId) => {
+              const { addProjectV2ItemById: { item } } = await github.graphql(`
+                mutation($p: ID!, $c: ID!) {
+                  addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+                }`, { p: process.env.PROJECT_ID, c: nodeId });
+              await github.graphql(`
+                mutation($p: ID!, $i: ID!, $f: ID!, $v: ProjectV2FieldValue!) {
+                  updateProjectV2ItemFieldValue(input: {projectId: $p, itemId: $i, fieldId: $f, value: $v}) {
+                    projectV2Item { id }
+                  }
+                }`, { p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
+                     v: { singleSelectOptionId: process.env.STATUS_CODE_REVIEW_PR } });
+            };
+
+            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} → Code Review / PR`);
+              }
+            } else {
+              await moveItem(pr.node_id);
+              console.log(`PR #${prNumber} → Code Review / PR (no linked issue)`);
+            }

package/CLAUDE.md

@@ -0,0 +1,9 @@
+# PDLC Stage Gate
+
+NEVER run `gh pr create` unless one of these is true:
+- The linked issue has label `stage:approval`
+- The branch name starts with `hotfix/`
+
+Advance stages first: `exploration` → `brainstorming` → `detailing` → `approval`
+
+The PreToolUse hook will block the action automatically if this rule is violated.

package/SETUP.md

@@ -149,6 +149,34 @@ If you don't use this, you can safely delete `templates/.github/workflows/qa-age
 
 ---
 
+## (Optional) Agentic Metrics — Weekly Report
+
+Every Sunday a `📊 Agentic Pulse` issue is created automatically in your repository with agentic-specific insights no off-the-shelf tool provides:
+
+- **Orphan issues** — open 14+ days with no linked PR (forgotten or blocked work)
+- **PR merge time trend** — week-over-week comparison (flow acceleration or slowdown)
+- **Rework rate** — PRs merged without extra commit sessions (agent or human first-shot rate)
+- **Unlinked PRs** — merged without `Closes #N` (traceability gaps)
+- **Stage Residence Time** — included automatically if your team uses `stage:*` labels _(Milestone 2)_
+
+The issue appears in your GitHub notifications automatically — zero extra setup, zero extra secrets.
+
+**To activate:**
+
+1. Copy the workflow to your repository:
+   ```bash
+   cp .agentic-pdlc/templates/.github/workflows/agentic-metrics.yml .github/workflows/agentic-metrics.yml
+   ```
+
+2. Commit and push. The first pulse runs next Sunday, or trigger it manually:
+   ```bash
+   gh workflow run agentic-metrics.yml
+   ```
+
+> **No additional secrets needed.** The workflow uses the standard `GITHUB_TOKEN` and creates a `metrics:weekly` label automatically on first run.
+
+---
+
 ## Final Verification Checklist
 
 - [ ] Board has 10 columns fully configured

package/adapters/claude-code/skill.md

@@ -25,7 +25,7 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
 1. **Language Detection:** Analyze the user's previous prompts and preferred language. Conduct this entire Setup Mode and ask all your interactive questions in that same language.
 2. Acknowledge that the framework is not yet set up.
 3. **Pre-filled Context:** Before asking any questions, read the following files if they exist:
-   - `.agentic-pdlc/cli-context.json` — written by the CLI. Contains `projectName`, `repoOwner`, `repoName`. Use these values directly and skip the corresponding questions.
+   - `.agentic-pdlc/cli-context.json` — written by the CLI. Contains `projectName`, `repoOwner`, `repoName`, `projectNumber`, `isOrg`, `boardUrl`, and `patAutoSet` (boolean). Use these values directly and skip the corresponding questions. Honor `patAutoSet` in Step 7 and `boardUrl` in Step 10.
    - `.agentic-pdlc/templates/docs/pdlc.md` — the CLI pre-fills PROJECT_ID, STATUS_FIELD_ID, REPO_OWNER, REPO_NAME, and all 9 column option IDs. If none of the values still contain `{{...}}` placeholders, skip the entire Board IDs question group.
    - `.agentic-pdlc/templates/.github/workflows/project-automation.yml` — the CLI also pre-fills all ID placeholders here. When writing the workflow file, the remaining `{{...}}` placeholders are only non-ID ones (project name, commands, etc.).
 4. Interactively ask the user only for the **missing values**, **one group at a time**:
@@ -42,7 +42,7 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
      - c) **Yes, activate** — *Uncomment the `move-violation-to-board` job in `project-automation.yml`.* → Activate immediately.
    - **QA Agent:** Ask: *"Do you want to use a QA agent to verify PRs automatically before Code Review?"* Present the options:
      - a) **No (Variant A)** — *PRs go straight to Code Review. Standard and simpler.*
-     - b) **Yes (Variant B), but I need help configuring it** — *PRs pass through a QA Agent before being reviewed. Requires a `GEMINI_API_KEY` secret (free tier available at ai.google.dev).* → Guide the user through configuration.
+     - b) **Yes (Variant B), but I need help configuring it** — *PRs pass through a QA Agent before being reviewed. Uses `GITHUB_TOKEN` — zero additional secrets.* → Guide the user through configuration.
      - c) **Yes (Variant B), I already have it configured** — *PRs pass through a QA Agent before being reviewed.* → Activate Variant B immediately: change `STATUS_CODE_REVIEW_PR` to `STATUS_TESTING` in the `move-card-on-pr-open` job and uncomment the `move-card-on-qa-pass` job in `project-automation.yml`.
    - **Implementation Agent:** Ask: *"Do you use an autonomous implementation agent? (It implements the features you approve for development)"* Present the options:
      - a) **No** — *No autonomous implementation agent.*
@@ -50,23 +50,33 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
      - c) **Other** — *Enter the agent's handle.*
 5. Generate and write the missing files replacing the `{{SCREAMING_SNAKE_CASE}}` placeholders using the templates in `.agentic-pdlc/templates/`.
 6. Offer to run the `gh` commands for labels (`spec:approved`, `pr:in-review`, `pr:approved`, `architecture-violation`).
-7. **Set up the `PROJECT_PAT` secret (required for board automation):**
-   The board automation workflows need a GitHub Personal Access Token (classic) with `project` scope. Without it, all board card movements will silently skip — no error, no cards moving.
-   - Go to: **github.com/settings/tokens** → *Generate new token (classic)*
-   - Select scopes: ✅ `repo` + ✅ `project`
-   - Copy the token, then run:
-     ```
-     gh secret set PROJECT_PAT --body "<your-token>"
-     ```
-   Wait for the user to confirm the secret is set before continuing.
+7. **`PROJECT_PAT` secret (required for board automation):**
+
+   Read `patAutoSet` from `.agentic-pdlc/cli-context.json`:
+
+   **If `patAutoSet === true`:** The CLI already configured this secret automatically. Print `✅ PROJECT_PAT is configured.` and continue to Step 8 — do not ask the user anything.
+
+   **If `patAutoSet === false` (org repo):** Show the block below and wait for the user to reply "done" or "secret set" before continuing:
+
+   > Your repo is in an organization. For security, `PROJECT_PAT` must be a dedicated PAT (not your personal OAuth token). Without it, all board card movements in CI will silently skip — no error surfaced.
+   >
+   > 1. Open: **github.com/settings/tokens** → *Generate new token (classic)*
+   > 2. Name: `PROJECT_PAT — <repo-name>`
+   > 3. Select scopes: ✅ `repo` + ✅ `project`
+   > 4. Copy the token, then run:
+   >    ```
+   >    gh secret set PROJECT_PAT --body "<your-token>" --repo <owner>/<repo>
+   >    ```
+   > 5. Reply **"done"** when finished.
 8. **IMPORTANT:** Delete the setup prompt file by running exactly:
    ```
    rm -f .agentic-setup.md .agentic-setup-prompt.md .agentic-pdlc/SETUP_PROMPT.md
    ```
    **Do NOT run `git add` or any other git command.** These files were never committed and do not exist in the git index. This command must run **before** the commit step.
 9. Commit everything with the message: `chore: setup agentic-pdlc framework`.
-10. Conclude Setup Mode. Read `projectNumber` from `.agentic-pdlc/cli-context.json` and show the user their board URL:
-    `https://github.com/users/{repoOwner}/projects/{projectNumber}/views/1?layout=board`
+10. Conclude Setup Mode. Read `boardUrl` from `.agentic-pdlc/cli-context.json` and show the user exactly this (do not reconstruct the URL — `boardUrl` already includes the correct `users/` or `orgs/` path segment and `?layout=board`):
+
+    `🎉 Setup complete! Your board: <boardUrl>`
 
 ---
 
@@ -86,7 +96,32 @@ This detects which optional agents (Jules, QA Agent, Sentinel) are already confi
 
 If `AGENTS.md` and `docs/pdlc.md` are present, you are in **Execution Mode**. 
 
-### 0. Board Labels — Mandatory at Every State Transition
+### 0. [FIRST] Issue Type Identification
+
+**Run before anything else — before `stage:exploration`, before reading code.**
+
+Reading the issue title and body for type inference is exempt from the `stage:exploration` requirement: it is metadata already present in the request, not code reading or skill invocation.
+
+1. Check if issue already has a `type:*` label (`type:us`, `type:task`, `type:bug`, `type:spike`) → if yes, skip to Section 0.1.
+2. Read issue title + body (metadata only — no code reading at this step).
+3. Classify using these rules:
+   - `type:task` — operational change, config, rename, docs update, non-functional (no user-facing behavior change)
+   - `type:bug` — something broken that should work
+   - `type:spike` — research/evaluation spike, never reaches Development
+   - `type:us` — new feature, behavioral change, anything product-facing
+4. Confidence ≥ 85% → add inferred label: `gh issue edit <N> --add-label "type:<inferred>"`
+5. Confidence < 85% → default to `type:us`: `gh issue edit <N> --add-label "type:us"`
+
+**Type drives the PDLC flow:**
+
+| Type | Flow |
+|---|---|
+| `type:us` | Full flow: exploration → brainstorming → Gate 1 → detailing → approval |
+| `type:task` | Skip brainstorming: exploration → detailing → approval |
+| `type:bug` | Skip brainstorming: exploration → detailing → approval |
+| `type:spike` | Skip brainstorming: exploration → detailing → conclusion comment (never reaches Development) |
+
+### 0.1 Board Labels — Mandatory at Every State Transition
 
 These label commands are non-negotiable. They run **before** the activity they announce — before reading code, before invoking any skill, before any other action.
 
@@ -98,8 +133,21 @@ These label commands are non-negotiable. They run **before** the activity they a
 
 No investigation, no skill invocation, no code reading happens before `stage:exploration` is applied. No architecture presentation starts before `stage:brainstorming` is set (and `stage:exploration` removed). No spec writing starts before `stage:detailing` is set (and `stage:brainstorming` removed).
 
+### 0.1 PR Stage Gate — Non-Negotiable
+
+**NEVER run `gh pr create` unless the linked issue has label `stage:approval`.**
+
+The PreToolUse hook enforces this automatically and will block the command. The only bypass is a branch prefixed with `hotfix/` — which requires explicit PM instruction, never agent self-authorization.
+
+Hotfix flow (only when PM explicitly requests it):
+```bash
+gh issue edit <N> --add-label "hotfix"
+git checkout -b hotfix/<N>-<description>
+# implement → gh pr create --label hotfix
+```
+
 ### 1. Daily Upstream Loop
-Your job is to move issues from "Idea" to "Detail Solution".
+Your job is to move issues from "💡 Idea - don't move manually to Exploration" to "📐 Detail Solution".
 When asked to work on a feature, you will:
 - Explore the code context.
 - Present architectural approaches (Brainstorming).

package/adapters/hooks/pdlc-stage-gate.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# PDLC Stage Gate — blocks gh pr create without stage:approval on linked issue.
+# Bypass: branch prefix hotfix/ skips all checks.
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | node -e "const d=JSON.parse(require('fs').readFileSync(0)); console.log(d.command || '')" 2>/dev/null || echo "")
+
+if ! echo "$COMMAND" | grep -q "gh pr create"; then
+  exit 0
+fi
+
+BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+
+if echo "$BRANCH" | grep -qE "^hotfix/"; then
+  echo "✅ PDLC: Hotfix branch — stage gate bypassed."
+  exit 0
+fi
+
+ISSUE_NUM=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
+
+if [ -z "$ISSUE_NUM" ]; then
+  echo "❌ PDLC Stage Gate: Cannot determine issue from branch '$BRANCH'."
+  echo "   Use: feat/<issue-number>-<description> or hotfix/<issue-number>-<description>"
+  exit 1
+fi
+
+LABELS=$(gh issue view "$ISSUE_NUM" --json labels --jq '[.labels[].name] | join(" ")' 2>/dev/null || echo "")
+
+if echo "$LABELS" | grep -qw "stage:approval"; then
+  echo "✅ PDLC: Issue #$ISSUE_NUM approved — gate passed."
+  exit 0
+fi
+
+if echo "$LABELS" | grep -qw "stage:development"; then
+  echo "✅ PDLC: Issue #$ISSUE_NUM in development (spec already approved) — gate passed."
+  exit 0
+fi
+
+STAGE=$(echo "$LABELS" | tr ' ' '\n' | grep "^stage:" | head -1 || echo "none")
+echo "❌ PDLC Stage Gate: Issue #$ISSUE_NUM is not approved."
+echo "   Current stage: $STAGE"
+echo "   Required: stage:approval or stage:development label on the issue."
+echo "   Emergency bypass: rename branch to hotfix/<issue-number>-<description>."
+exit 1

package/bin/cli.js

@@ -68,8 +68,8 @@ const i18n = {
   update_jules_header: t('— Jules (autonomous implementation agent) —', '— Jules (agente de implementação autônomo) —', '— Jules (agente de implementación autónomo) —'),
   update_jules_ask: t('  Which agent? (a) @google-labs-jules  (b) Other  (c) Skip: ', '  Qual agente? (a) @google-labs-jules  (b) Outro  (c) Pular: ', '  ¿Qué agente? (a) @google-labs-jules  (b) Otro  (c) Omitir: '),
   update_jules_ask_handle: t('  Agent handle (e.g. @my-agent): ', '  Handle do agente (ex: @meu-agente): ', '  Handle del agente (ej: @mi-agente): '),
-  update_qa_header: t('— QA Agent (AC verification via Gemini — free tier) —', '— QA Agent (verificação de ACs via Gemini — free tier) —', '— QA Agent (verificación de ACs via Gemini — free tier) —'),
-  update_qa_ask: t('  Activate? Requires GEMINI_API_KEY secret. (Y/n): ', '  Ativar? Requer secret GEMINI_API_KEY. (S/n): ', '  ¿Activar? Requiere el secret GEMINI_API_KEY. (S/n): '),
+  update_qa_header: t('— QA Agent (AC verification via GitHub Models — zero secrets) —', '— QA Agent (verificação de ACs via GitHub Models — zero secrets) —', '— QA Agent (verificación de ACs via GitHub Models — zero secrets) —'),
+  update_qa_ask: t('  Activate? Uses GITHUB_TOKEN — no extra secrets needed. (Y/n): ', '  Ativar? Usa GITHUB_TOKEN — nenhum secret extra necessário. (S/n): ', '  ¿Activar? Usa GITHUB_TOKEN — sin secrets adicionales. (S/n): '),
   update_sentinel_header: t('— Sentinel (architecture audit via Gemini Code Assist) —', '— Sentinel (auditoria de arquitetura via Gemini Code Assist) —', '— Sentinel (auditoría de arquitectura via Gemini Code Assist) —'),
   update_sentinel_ask: t('  Activate? Requires Gemini Code Assist CI job. (Y/n): ', '  Ativar? Requer CI job do Gemini Code Assist. (S/n): ', '  ¿Activar? Requiere CI job de Gemini Code Assist. (S/n): '),
 };
@@ -84,6 +84,11 @@ console.log(`${cyan}============================================================
 console.log(`${cyan}${i18n.welcome}${reset}`);
 console.log(`${cyan}================================================================${reset}\n`);
 
+function buildBoardUrl(repoOwner, projectNumber, isOrg) {
+  const segment = isOrg ? 'orgs' : 'users';
+  return `https://github.com/${segment}/${repoOwner}/projects/${projectNumber}/views/1?layout=board`;
+}
+
 // Helper function to recursively copy directories
 function copyDirSync(src, dest) {
   if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
@@ -121,6 +126,43 @@ async function runSetup() {
     process.exit(1);
   }
 
+  function getScopes() {
+    try {
+      const out = execFileSync('gh', ['api', 'user', '-i'], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+      const line = out.split('\n').find(l => l.toLowerCase().startsWith('x-oauth-scopes:'));
+      return line ? line.split(':').slice(1).join(':').split(',').map(s => s.trim()) : [];
+    } catch (e) {
+      return [];
+    }
+  }
+
+  const scopesBefore = getScopes();
+  if (scopesBefore.length > 0 && !scopesBefore.includes('project')) {
+    console.log(`${yellow}⚠️  Token missing 'project' scope — required for GitHub Projects board.${reset}`);
+    console.log(`${yellow}   Refreshing token now (browser may open)...${reset}\n`);
+    try {
+      execSync('gh auth refresh -h github.com -s project', { stdio: 'inherit' });
+    } catch (e) {
+      console.log(`${red}❌ Token refresh failed. Run manually: gh auth refresh -h github.com -s project${reset}`);
+      rl.close();
+      process.exit(1);
+    }
+    const scopesAfter = getScopes();
+    if (scopesAfter.length > 0 && !scopesAfter.includes('project')) {
+      console.log(`\n${red}❌ 'project' scope still missing after refresh.${reset}`);
+      console.log(`${yellow}   Active scopes: ${scopesAfter.join(', ')}${reset}`);
+      console.log(`${yellow}   Note: gh uses OAuth tokens — visible at github.com/settings/applications, not /settings/tokens${reset}`);
+      console.log(`${yellow}   Try manually: gh auth refresh -h github.com -s project${reset}`);
+      rl.close();
+      process.exit(1);
+    }
+    if (scopesAfter.length > 0) {
+      console.log(`\n${green}✅ Token refreshed. Active scopes: ${scopesAfter.join(', ')}${reset}\n`);
+    } else {
+      console.log(`\n${green}✅ Token refreshed with 'project' scope.${reset}\n`);
+    }
+  }
+
   const agentAnswer = await askQuestion(i18n.ask_agent);
   const agent = agentAnswer.trim().toLowerCase();
   if (!['claude', 'cursor', 'copilot'].includes(agent)) {
@@ -190,14 +232,14 @@ async function runSetup() {
   let ownerId, projectId, projectNumber;
   try {
     if (isOrg) {
-      const orgOutput = execFileSync('gh', ['api', 'graphql', '-f', 'query=query($login: String!) { organization(login: $login) { id } }', '-f', `login=${repoOwner}`, '--jq', '.data.organization.id']).toString().trim();
+      const orgOutput = execFileSync('gh', ['api', 'graphql', '-f', 'query=query($login: String!) { organization(login: $login) { id } }', '-f', `login=${repoOwner}`, '--jq', '.data.organization.id'], { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
       ownerId = orgOutput;
     } else {
-      const userOutput = execFileSync('gh', ['api', 'graphql', '-f', 'query={ viewer { id } }', '--jq', '.data.viewer.id']).toString().trim();
+      const userOutput = execFileSync('gh', ['api', 'graphql', '-f', 'query={ viewer { id } }', '--jq', '.data.viewer.id'], { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
       ownerId = userOutput;
     }
 
-    const projectCreateRaw = execFileSync('gh', ['api', 'graphql', '-f', 'query=mutation($owner: ID!, $title: String!) { createProjectV2(input: {ownerId: $owner, title: $title}) { projectV2 { id number } } }', '-f', `owner=${ownerId}`, '-f', `title=${boardName}`]).toString().trim();
+    const projectCreateRaw = execFileSync('gh', ['api', 'graphql', '-f', 'query=mutation($owner: ID!, $title: String!) { createProjectV2(input: {ownerId: $owner, title: $title}) { projectV2 { id number } } }', '-f', `owner=${ownerId}`, '-f', `title=${boardName}`], { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
     const projectCreateResponse = JSON.parse(projectCreateRaw);
     if (projectCreateResponse.errors) {
       throw new Error(projectCreateResponse.errors.map(e => e.message).join('; '));
@@ -217,7 +259,14 @@ async function runSetup() {
     }
 
   } catch (err) {
-    console.log(`  ${i18n.project_err}${err.message}`);
+    const isScopeError = (err.message || '').includes("required scopes") || (err.stderr || '').toString().includes("required scopes");
+    if (isScopeError) {
+      console.log(`  ${red}❌ Token missing 'project' scope.${reset}`);
+      console.log(`  ${yellow}Fix: gh auth refresh -s project${reset}`);
+      console.log(`  ${yellow}Then re-run: npx create-agentic-pdlc${reset}`);
+    } else {
+      console.log(`  ${i18n.project_err}${err.message}`);
+    }
   }
 
   let statusFieldId;
@@ -278,6 +327,23 @@ async function runSetup() {
     }
   }
 
+  // Auto-provision PROJECT_PAT for personal repos
+  let patAutoSet = false;
+  if (projectId && !isOrg) {
+    try {
+      const tokenOut = execFileSync('gh', ['auth', 'token'], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' }).trim();
+      if (tokenOut) {
+        execFileSync('gh', ['secret', 'set', 'PROJECT_PAT', '--body', tokenOut, '--repo', repo], { stdio: ['ignore', 'pipe', 'pipe'] });
+        patAutoSet = true;
+        console.log(`\n${green}✅ PROJECT_PAT secret set automatically (uses your gh OAuth token).${reset}`);
+      }
+    } catch (err) {
+      console.log(`\n${yellow}⚠️  Could not auto-set PROJECT_PAT. Agent will guide manual setup.${reset}`);
+    }
+  } else if (projectId && isOrg) {
+    console.log(`\n${yellow}ℹ️  Org repo detected — PROJECT_PAT will require manual setup for security.${reset}`);
+  }
+
   console.log(`\n${yellow}${i18n.scaffolding}${reset}`);
 
   // We copy the templates folder so the agent has the real text logic to replace and rename
@@ -311,7 +377,11 @@ async function runSetup() {
       }
 
       fs.writeFileSync(pdlcDest, pdlcContent);
-      console.log(`${i18n.pdlc_prefilled}`);
+      if (projectId && statusFieldId && Object.keys(optionMap).length > 0) {
+        console.log(`${i18n.pdlc_prefilled}`);
+      } else {
+        console.log(`${yellow}⚠️  pdlc.md copied — Project IDs not filled (board creation failed). Re-run after fixing token.${reset}`);
+      }
     }
 
     // Pre-fill project-automation.yml with the same IDs so the agent doesn't need to map them
@@ -338,11 +408,43 @@ async function runSetup() {
   // Write CLI context for the agent to consume in Setup Mode
   try {
     const cliContextPath = path.join(targetDir, '.agentic-pdlc', 'cli-context.json');
-    fs.writeFileSync(cliContextPath, JSON.stringify({ projectName, repoOwner, repoName, projectNumber }, null, 2));
+    const boardUrl = projectNumber ? buildBoardUrl(repoOwner, projectNumber, isOrg) : null;
+    fs.writeFileSync(cliContextPath, JSON.stringify({
+      projectName,
+      repoOwner,
+      repoName,
+      projectNumber,
+      isOrg,
+      boardUrl,
+      patAutoSet
+    }, null, 2));
   } catch (err) {
     // Non-fatal — agent will ask for the values instead
   }
 
+  // Install PDLC stage gate hook (all agents)
+  const hookSrc = path.join(sourceDir, 'adapters', 'hooks', 'pdlc-stage-gate.sh');
+  const hookDir = path.join(targetDir, '.agentic-pdlc', 'hooks');
+  const hookDest = path.join(hookDir, 'pdlc-stage-gate.sh');
+  if (fs.existsSync(hookSrc)) {
+    fs.mkdirSync(hookDir, { recursive: true });
+    fs.copyFileSync(hookSrc, hookDest);
+    fs.chmodSync(hookDest, '755');
+  }
+  const claudeSettingsDir = path.join(targetDir, '.claude');
+  const claudeSettingsPath = path.join(claudeSettingsDir, 'settings.json');
+  if (!fs.existsSync(claudeSettingsPath)) {
+    fs.mkdirSync(claudeSettingsDir, { recursive: true });
+    fs.writeFileSync(claudeSettingsPath, JSON.stringify({
+      hooks: {
+        PreToolUse: [{
+          matcher: 'Bash',
+          hooks: [{ type: 'command', command: 'bash .agentic-pdlc/hooks/pdlc-stage-gate.sh' }]
+        }]
+      }
+    }, null, 2) + '\n');
+  }
+
   // Handle the specific setup instructions target
   const claudeSetupSrc = path.join(sourceDir, 'adapters', 'claude-code', 'skill.md');
   const cursorSetupSrc = path.join(sourceDir, 'adapters', 'cursor', 'rules.md');
@@ -536,9 +638,9 @@ async function runUpdate() {
     if (!['n', 'no', 'não', 'nao'].includes(answer)) {
       activateQaAgent(paPath);
       results.push(t(
-        '✅  QA Agent configured — Variant B activated\n     Next: gh secret set GEMINI_API_KEY --body "<your-key>"',
-        '✅  QA Agent configurado — Variant B ativado\n     Próximo: gh secret set GEMINI_API_KEY --body "<sua-chave>"',
-        '✅  QA Agent configurado — Variant B activado\n     Siguiente: gh secret set GEMINI_API_KEY --body "<tu-clave>"'
+        '✅  QA Agent configured — Variant B activated (uses GITHUB_TOKEN, no extra secrets needed)',
+        '✅  QA Agent configurado — Variant B ativado (usa GITHUB_TOKEN, nenhum secret extra necessário)',
+        '✅  QA Agent configurado — Variant B activado (usa GITHUB_TOKEN, sin secrets adicionales)'
       ));
     } else {
       results.push(t('⏭  QA Agent — skipped', '⏭  QA Agent — pulado', '⏭  QA Agent — omitido'));

package/docs/pdlc.md

@@ -4,7 +4,7 @@
 
 | Column | Meaning | Who moves the card |
 |---|---|---|
-| 💡 Idea | Backlog — every new issue lands here | Manual |
+| 💡 Idea — don't move manually to Exploration | Backlog — tell agent: "work on issue #XX" | Don't move manually |
 | 🔍 Exploration | AI is analyzing code and context | Label `stage:exploration` |
 | 🧠 Brainstorming | AI proposed approaches and trade-offs | Label `stage:brainstorming` |
 | 📐 Detail Solution | AI is writing the technical spec | Label `stage:detailing` |
@@ -72,6 +72,10 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | `spec:approved` | Issue | Green | Gate 2 — agent is cleared to implement |
 | `pr:in-review` | PR | Yellow | Awaiting code review |
 | `pr:approved` | PR | Green | Code review approved |
+| `type:us` | Issue | Blue | New feature or behavioral change — full flow |
+| `type:task` | Issue | Yellow | Operational/non-functional change — skips brainstorming |
+| `type:bug` | Issue | Red | Something broken — skips brainstorming |
+| `type:spike` | Issue | Gray | Research/evaluation — never reaches Development |
 
 ## Approval Gates
 
@@ -85,10 +89,16 @@ This triggers the implementation agent via `agent-trigger.yml`.
 
 ## Shortcuts by Type
 
-- **BUG** — Skips Brainstorming; enters Detail Solution with diagnostics + fix.
-- **TASK** — Skips Brainstorming; enters Detail Solution with operational steps.
-- **SPIKE** — Never reaches Development; delivery is a concluding comment.
-- **US** — Full flow observing both gates.
+The `type:*` label is the authoritative signal — set automatically by the agent via type inference (see `adapters/claude-code/skill.md`). Title prefixes (`🔧 TASK:`, `👤 US:`) are hints for humans; the label drives the flow.
+
+| Label | Flow |
+|---|---|
+| `type:us` | Full flow — exploration → brainstorming → Gate 1 → detailing → approval |
+| `type:task` | Skips brainstorming — exploration → detailing → approval |
+| `type:bug` | Skips brainstorming — exploration → detailing → approval |
+| `type:spike` | Skips brainstorming — exploration → detailing → conclusion comment (never reaches Development) |
+
+If no `type:*` label present and agent confidence < 85%, defaults to `type:us` (safe fallback — never skips gates by omission).
 
 ## Definition of Done
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-pdlc",
-  "version": "2.1.6",
+  "version": "2.2.1",
   "description": "Agentic PDLC Framework - Conversational setup for your AI coding assistants",
   "type": "commonjs",
   "bin": {

package/pr_comments.json

@@ -0,0 +1,20 @@
+{
+  "body": "![security-high](https://www.gstatic.com/codereviewagent/security-high-priority.svg) ![high](https://www.gstatic.com/codereviewagent/high-priority.svg)\n\nThe use of `execSync` with template literals containing user-provided variables (such as `${repo}`, `${repoOwner}`, `${repoName}`, and `${branchName}`) is vulnerable to command injection. If a user provides a malicious repository URL or branch name containing shell metacharacters (e.g., `; rm -rf /`), they could execute arbitrary shell commands. It is highly recommended to use `spawnSync` with an arguments array to avoid shell interpretation, or at least sanitize and quote the inputs strictly.",
+  "path": "bin/cli.js",
+  "line": 155
+}
+{
+  "body": "![medium](https://www.gstatic.com/codereviewagent/medium-priority.svg)\n\nThe required status check context `\"Sentinel / CI\"` does not match any of the workflow or job names defined in the provided templates (e.g., `PDLC Board Automation` or `Detect Project Board Drift`). This will cause pull requests to be permanently blocked as the required check will never be reported. Based on the provided templates, `\"Detect Project Board Drift\"` seems to be the intended health check job name.\n\n```suggestion\n    required_status_checks: { strict: true, checks: [{ context: \"Detect Project Board Drift\" }] },\n```",
+  "path": "bin/cli.js",
+  "line": 165
+}
+{
+  "body": "![medium](https://www.gstatic.com/codereviewagent/medium-priority.svg)\n\nParsing `updateOutput` directly can throw a `SyntaxError` if the command fails or returns an empty/invalid response. Although it's inside a `try...catch` block, checking if the output is truthy before parsing and using optional chaining provides better resilience and prevents the script from crashing on unexpected API responses.\n\n```suggestion\n        const jsonResponse = updateOutput ? JSON.parse(updateOutput) : null;\n        const returnedOptions = jsonResponse?.data?.updateProjectV2SingleSelectField?.projectV2SingleSelectField?.options || [];\n```",
+  "path": "bin/cli.js",
+  "line": 248
+}
+{
+  "body": "![medium](https://www.gstatic.com/codereviewagent/medium-priority.svg)\n\nTypo in Spanish translation: \"arquivo\" is Portuguese. In Spanish, it should be \"archivo\".\n\n```suggestion\n      console.log(`${cyan}>>> Español: \"Lea el archivo .agentic-setup.md e inicie el Setup Mode\"${reset}`);\n```",
+  "path": "bin/cli.js",
+  "line": 314
+}