create-agentic-pdlc 2.3.0 → 2.4.0

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

@@ -31,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: |
@@ -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) {
@@ -83,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
@@ -91,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: |
@@ -121,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: |
@@ -152,7 +185,7 @@ jobs:
                 });
             };
 
-            const stageLabelsToRemove = ['stage:development', 'stage:brainstorming', 'stage:detailing', 'stage:approval', 'jules', 'agent:working'];
+            const stageLabelsToRemove = ['stage:development', 'stage:brainstorming', 'stage:detailing', 'jules'];
 
             if (linkedIssues.length > 0) {
               for (const n of linkedIssues) {
@@ -181,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: |
@@ -215,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 {
@@ -232,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: |
@@ -251,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: |
@@ -279,6 +315,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 {
@@ -291,7 +330,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: |
@@ -300,7 +339,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/.github/workflows/qa-agent.yml

@@ -19,7 +19,7 @@ jobs:
       STATUS_FIELD_ID: "PVTSSF_lAHODpFFL84BXg7hzhStRHI"
       STATUS_CODE_REVIEW_PR: "86ca9720"
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5.0.1
         with:
           fetch-depth: 0
 
@@ -34,7 +34,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 // ""')
@@ -53,20 +53,30 @@ jobs:
             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)
+          # Serialize prompt as JSON string and call GitHub Models API (3 attempts, 20s backoff)
           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")
+          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_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 marks this check as failed; qa-gate.yml enforces the merge block via infra:qa-broken label
+            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")')
@@ -81,11 +91,12 @@ jobs:
           else
             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
 
       - name: Move board card to Code Review on qa:approved
         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/.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

package/AGENTS.md

@@ -27,14 +27,55 @@ Always start from the current `main` HEAD. Never work over stale snapshots.
 ## Mandatory Workflow
 
 0. **Identity**: Always prefix your GitHub comments with `🤖 **Agent:** ` to distinguish yourself.
-1. **Initial State**: When beginning work on a new issue, your very first action must be to apply the `stage:brainstorming` label using the GitHub CLI (`gh issue edit <N> --add-label "stage:brainstorming"`).
-2. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
-3. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
-4. Read all files mentioned in the issue's technical context.
-5. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
-6. Run tests: `echo "No tests/build needed."`
-7. Run typecheck: `echo "No typecheck needed."`
-8. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+1. **Stage Check**: Before applying any label or taking any action, run `gh issue view <N> --json labels,title` to determine the issue's current stage. State: *"Issue #N — [title] — is currently at `<stage>`. Requesting confirmation to advance to `<next>`."* Wait for an explicit stage-advancement signal in this conversation turn. A prioritization signal ("work on X", "tackle X next") does **not** count as confirmation — only an explicit signal counts (e.g. "start brainstorming", "yes advance", "go"). **Exceptions — skip this step and proceed directly**:
+   - `spec:approved` → begin implementation (gate already passed)
+   - `stage:development` or `stage:testing` → issue is owned by automation; do not intervene unless explicitly asked to fix a specific problem
+   - `stage:approval` → spec already written; wait for PM to add `spec:approved` before doing anything
+2. **Initial State**: Apply the `stage:brainstorming` label using the GitHub CLI (`gh issue edit <N> --add-label "stage:brainstorming"`). **Exception — pre-spec'd issue**: if the issue body already contains all required spec sections (`## Problem`, `## Solution`, `## Acceptance Criteria`, `## Edge Cases`, `## Out of Scope`, `## Files to Modify`) — all present and non-empty — apply `stage:approval` directly in a single call instead, skipping `stage:brainstorming` and `stage:detailing`.
+3. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
+4. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
+5. Read all files mentioned in the issue's technical context.
+6. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
+7. Run tests: `echo "No tests/build needed."`
+8. Run typecheck: `echo "No typecheck needed."`
+9. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+
+## Spec Format
+
+When writing or rewriting an issue body during detailing, include ALL sections below. Omitting any section blocks `stage:approval`.
+
+```
+## Problem
+[1-3 sentences. What fails. Who affected. Measured impact.]
+
+## Sprint Goal / Success Metrics
+| Metric | Baseline | Target | When |
+|--------|----------|--------|------|
+
+## Solution
+[Behavioral description of what is built. No implementation details.]
+
+## Acceptance Criteria
+**AC1 — [name]**
+- Given [precondition]
+- When [action]
+- Then [outcome]
+
+## Edge Cases
+- EC1: [condition] → [expected behavior]
+
+## Out of Scope
+- [item] — reason
+
+## Non-Functional Requirements
+- Performance: [metric with number]
+- Security: [constraint]
+- Reliability: [constraint]
+> For pure docs/markdown issues with zero runtime behavior, include the NFRs section and state "N/A".
+
+## Files to Modify
+- `path/to/file` — what changes
+```
 
 ## What NOT to do
 
@@ -50,3 +91,4 @@ Always start from the current `main` HEAD. Never work over stale snapshots.
 - **Lint/Types:** `echo "No tests/build needed."`
 - **Typecheck:** `echo "No typecheck needed."`
 - **Build:** `echo "No tests/build needed."`
+- **Canonical secret name:** `PROJECT_TOKEN` (not `PROJECT_PAT`) — use this in all workflow files, both live and templates

package/CLAUDE.md

@@ -33,6 +33,8 @@ The PreToolUse hook will block `gh pr create` automatically if this rule is viol
 
 **Detailing is fully autonomous.** Write the complete spec, add it to the issue, advance to `stage:approval` — no confirmation needed. Then **stop and wait** for human to add `spec:approved` before any implementation.
 
+**Spec destination: the issue body.** Write spec content to the issue body using `gh issue edit <N> --body "..."` — not to a file. A file is acceptable as optional reference only. Automation checks the issue body for `## Acceptance Criteria` and `## Files to Modify` to advance the stage; content that exists only in a file is invisible to it.
+
 ## Stage Transition Rules (non-negotiable)
 
 MUST apply `stage:brainstorming` label immediately on starting work — before

package/SETUP.md

@@ -63,7 +63,7 @@ npx create-agentic-pdlc
 The CLI will:
 1. Ask you which AI Agent you use (Claude Code, Cursor, etc.).
 2. Copy the system instructions pointing to our interactive Setup Mode.
-3. Automatically download the base templates to `.agentic-pdlc/templates/`.
+3. Automatically install the base templates into your project.
 
 Once the CLI finishes, it will instruct you to open your AI agent and run the **Setup Mode**. Your AI agent will then ask you the required project variables interactively and generate `AGENTS.md`, `docs/pdlc.md`, and the GitHub Actions for you!
 
@@ -169,6 +169,7 @@ The issue appears in your GitHub notifications automatically — zero extra setu
    ```bash
    cp .agentic-pdlc/templates/.github/workflows/agentic-metrics.yml .github/workflows/agentic-metrics.yml
    ```
+   > If the file is missing, re-run `npx create-agentic-pdlc` to update your installed templates.
 
 2. Commit and push. The first pulse runs next Sunday, or trigger it manually:
    ```bash

package/adapters/claude-code/skill.md

@@ -106,21 +106,21 @@ If `AGENTS.md` and `docs/pdlc.md` are present, you are in **Execution Mode**.
 
 Reading the issue title and body for type inference is exempt from the initial label 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.
+1. Check if issue already has a `type:*` label (`type:feature`, `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
+   - `type:feature` — 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"`
+5. Confidence < 85% → default to `type:feature`: `gh issue edit <N> --add-label "type:feature"`
 
 **Type drives the PDLC flow:**
 
 | Type | Flow |
 |---|---|
-| `type:us` | brainstorming → Gate 1 → detailing → approval |
+| `type:feature` | brainstorming → Gate 1 → detailing → approval |
 | `type:task` | brainstorming → Gate 1 → detailing → approval |
 | `type:bug` | brainstorming → Gate 1 → detailing → approval |
 | `type:spike` | brainstorming → Gate 1 → detailing → conclusion comment (never reaches Development) |
@@ -157,18 +157,39 @@ When asked to work on a feature, you will:
 - Stop and wait for the human PM's explicit approval (Gate 1).
 
 ### 2. Creating the Spec
-Once approved, you will detail the solution directly into the GitHub Issue body. Focus on precise Acceptance Criteria.
-**IMPORTANT:** You must always rewrite the full issue body to include both the user story and the Acceptance Criteria. Do not simply append the ACs to the existing text. Use this format:
+Once approved, detail the solution directly into the GitHub Issue body. Always rewrite the full issue body — never append only ACs to existing text. Include ALL sections below. Omitting any section blocks `stage:approval`. Use this format:
 
 ```
-**As** [user],
-**I want** [action],
-**so that** [benefit].
+## Problem
+[1-3 sentences. What fails. Who affected. Measured impact.]
 
----
+## Sprint Goal / Success Metrics
+| Metric | Baseline | Target | When |
+|--------|----------|--------|------|
+
+## Solution
+[Behavioral description of what is built. No implementation details.]
 
 ## Acceptance Criteria
-...
+**AC1 — [name]**
+- Given [precondition]
+- When [action]
+- Then [outcome]
+
+## Edge Cases
+- EC1: [condition] → [expected behavior]
+
+## Out of Scope
+- [item] — reason
+
+## Non-Functional Requirements
+- Performance: [metric with number]
+- Security: [constraint]
+- Reliability: [constraint]
+> For pure docs/markdown issues with zero runtime behavior, include the NFRs section and state "N/A".
+
+## Files to Modify
+- `path/to/file` — what changes
 ```
 
 ### 3. Handoff

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

@@ -26,19 +26,14 @@ fi
 
 LABELS=$(gh issue view "$ISSUE_NUM" --json labels --jq '[.labels[].name] | join(" ")' 2>/dev/null || echo "")
 
-if echo "$LABELS" | grep -qw "spec:approved"; then
-  echo "✅ PDLC: Issue #$ISSUE_NUM spec approved by PM — 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."
+if echo "$LABELS" | grep -qw "spec:approved" || echo "$LABELS" | grep -qw "stage:approval" || echo "$LABELS" | grep -qw "stage:development" || echo "$LABELS" | grep -qw "stage:testing" || echo "$LABELS" | grep -qw "human-approved"; then
+  echo "✅ PDLC: Issue #$ISSUE_NUM 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: spec:approved (set by human PM) 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: rename branch to hotfix/<issue-number>-<description>."
 exit 1

package/bin/cli.js

@@ -41,10 +41,10 @@ const i18n = {
   invalid_repo: t('❌ Invalid repository URL. Expected format: https://github.com/OWNER/REPO', '❌ URL de repositório inválida. Formato esperado: https://github.com/OWNER/REPO', '❌ URL de repositorio inválida. Formato esperado: https://github.com/OWNER/REPO'),
   ask_org: t('Does this repository belong to a personal User account (e.g., github.com/rafaeltcosta86) or an Organization (e.g., github.com/google-labs)? (user/org): ', 'Esse repositório pertence a um Usuário pessoal (ex: github.com/rafaeltcosta86) ou a uma Organização (ex: github.com/google-labs)? (user/org): ', '¿Este repositorio pertenece a un Usuario personal (ej: github.com/rafaeltcosta86) o a una Organización (ej: github.com/google-labs)? (user/org): '),
   starting_setup: t('Starting automated repository setup...', 'Iniciando o setup automatizado do repositório...', 'Iniciando la configuración automatizada del repositorio...'),
-  creating_labels: t('[1/2] Creating repository labels...', '[1/2] Criando labels no repositório...', '[1/2] Creando etiquetas (labels) en el repositorio...'),
+  creating_labels: t('[1/3] Creating repository labels...', '[1/3] Criando labels no repositório...', '[1/3] Creando etiquetas (labels) en el repositorio...'),
   label_ok: t('✅ Label created: ', '✅ Label criada: ', '✅ Etiqueta creada: '),
   label_warn: t('⚠️ Failed to create label (might already exist): ', '⚠️ Falha ao criar label (talvez já exista): ', '⚠️ Fallo al crear etiqueta (quizás ya exista): '),
-  creating_project: t('[2/2] Creating Project V2 Board...', '[2/2] Criando Project V2 Board...', '[2/2] Creando Project V2 Board...'),
+  creating_project: t('[2/3] Creating Project V2 Board...', '[2/3] Criando Project V2 Board...', '[2/3] Creando Project V2 Board...'),
   project_ok: t('✅ Project created (ID: ', '✅ Projeto criado (ID: ', '✅ Proyecto creado (ID: '),
   project_err: t('❌ Failed to create project. Error: ', '❌ Falha ao criar o projeto. Erro: ', '❌ Fallo al crear el proyecto. Error: '),
   link_project_ok: t('✅ Project linked to repository.', '✅ Projeto vinculado ao repositório.', '✅ Proyecto vinculado al repositorio.'),
@@ -72,6 +72,9 @@ const i18n = {
   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): '),
+  configuring_protection: t('[3/3] Configuring branch protection...', '[3/3] Configurando proteção de branch...', '[3/3] Configurando protección de rama...'),
+  protection_ok: t('✅ Branch protection set — required checks: PDLC Stage Gate, QA Gate.', '✅ Proteção de branch configurada — checks obrigatórios: PDLC Stage Gate, QA Gate.', '✅ Protección de rama configurada — checks requeridos: PDLC Stage Gate, QA Gate.'),
+  protection_warn: t('⚠️  Branch protection could not be set automatically.\n     Set required checks manually: Settings → Branches → main → Required status checks.\n     Required: "PDLC Stage Gate" and "QA Gate"', '⚠️  Proteção de branch não pôde ser configurada automaticamente.\n     Configure manualmente: Settings → Branches → main → Required status checks.\n     Obrigatórios: "PDLC Stage Gate" e "QA Gate"', '⚠️  No se pudo configurar la protección de rama automáticamente.\n     Configúralo en: Settings → Branches → main → Required status checks.\n     Requeridos: "PDLC Stage Gate" y "QA Gate"'),
 };
 
 const cyan = '\x1b[36m';
@@ -355,6 +358,24 @@ async function runSetup() {
     console.log(`\n${yellow}ℹ️  Org repo detected — PROJECT_PAT will require manual setup for security.${reset}`);
   }
 
+  // Branch protection — require PDLC Stage Gate + QA Gate on default branch
+  console.log(`\n${cyan}${i18n.configuring_protection}${reset}`);
+  try {
+    const defaultBranch = execFileSync('gh', ['api', `repos/${repo}`, '--jq', '.default_branch'],
+      { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' }).trim() || 'main';
+    const protectionPayload = JSON.stringify({
+      required_status_checks: { strict: false, contexts: ['PDLC Stage Gate', 'QA Gate'] },
+      enforce_admins: false,
+      required_pull_request_reviews: null,
+      restrictions: null
+    });
+    execFileSync('gh', ['api', `repos/${repo}/branches/${defaultBranch}/protection`, '--method', 'PUT', '--input', '-'],
+      { input: protectionPayload, stdio: ['pipe', 'ignore', 'pipe'] });
+    console.log(`  ${green}${i18n.protection_ok}${reset}`);
+  } catch (_) {
+    console.log(`  ${yellow}${i18n.protection_warn}${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

package/docs/pdlc.md

@@ -53,7 +53,7 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 ```
 [icon] [PREFIX]: [short description, imperative tense]
 
-👤 US:     user story
+✨ feat:   new feature or behavioral change
 🐛 BUG:    bug
 🔧 TASK:   operational task
 🔬 SPIKE:  exploration/evaluation spike
@@ -69,7 +69,7 @@ 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:feature` | Issue | Blue | New feature or behavioral change — full flow |
 | `type:task` | Issue | Yellow | Operational/non-functional change — full flow |
 | `type:bug` | Issue | Red | Something broken — full flow |
 | `type:spike` | Issue | Gray | Research/evaluation — never reaches Development |
@@ -90,12 +90,12 @@ The `type:*` label is the authoritative signal — set automatically by the agen
 
 | Label | Flow |
 |---|---|
-| `type:us` | brainstorming → Gate 1 → detailing → approval |
+| `type:feature` | brainstorming → Gate 1 → detailing → approval |
 | `type:task` | brainstorming → Gate 1 → detailing → approval |
 | `type:bug` | brainstorming → Gate 1 → detailing → approval |
 | `type:spike` | brainstorming → Gate 1 → 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).
+If no `type:*` label present and agent confidence < 85%, defaults to `type:feature` (safe fallback — never skips gates by omission).
 
 ## Bypass Mechanism
 
@@ -103,7 +103,7 @@ Agents MUST NOT skip any stage. The ONLY authorized bypasses are:
 
 | Mechanism | Who authorizes | What it bypasses |
 |---|---|---|
-| `human-approved` label on issue | PM (human) only | All stage gates |
+| `human-approved` label on issue | PM (human) only | All stage gates — automation adds `qa:approved` to linked PRs, moving card to Code Review / PR. `pdlc-stage-gate` accepts `stage:testing` as a valid post-gate state. |
 | Branch prefix `hotfix/` | PM (human) only | PR gate only |
 
 Agents MUST NOT self-authorize a bypass. Stop and ask the PM explicitly.