create-agentic-pdlc 1.2.1 → 2.0.0

package/SETUP.md

@@ -41,7 +41,7 @@ Note down the `PROJECT_ID` and the `STATUS_FIELD_ID` for future steps.
 ```bash
 REPO="owner/repo"
 gh label create "spec:approved"          --repo $REPO --color "0e8a16" --description "Spec approved — agent can implement"
-gh label create "pr:review"              --repo $REPO --color "e4e669" --description "PR awaiting code review"
+gh label create "pr:in-review"           --repo $REPO --color "e4e669" --description "PR awaiting code review"
 gh label create "pr:approved"            --repo $REPO --color "0e8a16" --description "PR approved, ready for merge"
 gh label create "architecture-violation" --repo $REPO --color "d93f0b" --description "Invariant violation detected by CI"
 ```
@@ -122,13 +122,52 @@ For each known idea or feature, create an issue using the convention:
 gh issue create \
   --repo owner/repo \
   --title "👤 US: [short description]" \
-  --body "Initial idea issue. Spec to be detailed."
+  --body "**As** [user],
+**I want** [action],
+**so that** [benefit].
+
+---
+
+Initial idea issue. Spec to be detailed."
 ```
 
 Move the issues to the `Idea` column on the board matching your setup.
 
 ---
 
+## (Optional) Architecture Violation Integration
+
+If your project uses an automated architecture auditing tool (e.g., a CI job that creates issues with an `architecture-violation` label), the Setup Mode can automatically add a GitHub Actions job to `project-automation.yml` that moves these issues to the `Idea` column.
+
+If you skipped this during setup but want to add it later, you can append the following job to `.github/workflows/project-automation.yml` under the `jobs` section:
+
+```yaml
+  move-violation-to-board:
+    name: architecture-violation → 💡 Idea
+    if: github.event_name == 'issues' && github.event.label.name == 'architecture-violation'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PROJECT_TOKEN }}
+          script: |
+            const issueNodeId = context.payload.issue.node_id;
+            const addResult = await github.graphql(`
+              mutation($p: ID!, $c: ID!) {
+                addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+              }`, { p: process.env.PROJECT_ID, c: issueNodeId });
+            const itemId = addResult.addProjectV2ItemById.item.id;
+            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: itemId, f: process.env.STATUS_FIELD_ID,
+                    v: { singleSelectOptionId: process.env.STATUS_IDEA } });
+```
+
+---
+
 ## Final Verification Checklist
 
 - [ ] Board has 10 columns fully configured

package/adapters/claude-code/skill.md

@@ -13,19 +13,22 @@ If the user invokes you in a new project, you must first check if the PDLC artif
 Specifically, check for:
 - `AGENTS.md`
 - `docs/pdlc.md`
+- `.github/CODEOWNERS`
 - `.github/workflows/project-automation.yml`
 - `.github/workflows/agent-trigger.yml`
+- `.github/workflows/pdlc-health-check.yml`
 
 If any of these files are missing, you are in **Setup Mode**. Do not proceed with feature requests until setup is complete.
 1. Acknowledge that the framework is not yet set up.
 2. Interactively ask the user for required values **one group at a time**:
-   - **Project basics:** Project Name, Description, Technical Stack (Structure).
+   - **Project basics:** Project Name, Description, Technical Stack (Structure), and GitHub Username (for CODEOWNERS security).
    - **Commands:** Test command, Lint command, Build command.
    - **Invariants:** Critical business rules agents must never violate (e.g. Human-in-the-loop).
    - **Board IDs:** PROJECT_ID, STATUS_FIELD_ID, column option IDs (provide standard PDLC options: Idea, Exploration, Brainstorming, Detail Solution, Approval, Development, Testing, Code Review / PR, Merge, Production). Allow user to answer "skip", which means you leave the placeholders intact.
+   - **Architecture Violation:** Ask "Does your project use an automated architecture auditing tool (e.g., a CI job that creates issues with an `architecture-violation` label)?". If yes, replace `{{OPTIONAL_ARCHITECTURE_VIOLATION_JOB}}` in `project-automation.yml` with the job definition (available in the framework documentation). If no, ask if they would like help implementing one, reminding them that it significantly improves their agentic development process. If they decline, remove the placeholder.
    - **Implementation agent handle:** e.g., `@google-labs-jules`, or "none".
 3. Generate and write the missing files replacing the `{{SCREAMING_SNAKE_CASE}}` placeholders using the templates logic you know (usually they reside in standard Agentic PDLC templates).
-4. Offer to run the `gh` commands for labels (`spec:approved`, `pr:review`, `pr:approved`, `architecture-violation`).
+4. Offer to run the `gh` commands for labels (`spec:approved`, `pr:in-review`, `pr:approved`, `architecture-violation`).
 5. Commit everything with the message: `chore: setup agentic-pdlc framework`.
 6. Conclude Setup Mode.
 
@@ -44,6 +47,18 @@ When asked to work on a feature, you will:
 
 ### 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:
+
+```
+**As** [user],
+**I want** [action],
+**so that** [benefit].
+
+---
+
+## Acceptance Criteria
+...
+```
 
 ### 3. Handoff
 Do not write code for downstream features! Your goal is to refine the Spec, so the human Tech Lead can label the issue `spec:approved`. This label triggers the downstream agent via `agent-trigger.yml`.

package/docs/flow.md

@@ -0,0 +1,160 @@
+# PDLC Flow: From Idea to Production
+
+This document describes the full lifecycle of a card on the agentic-pdlc board — who acts at each stage, what triggers each transition, which labels are added or removed, and where human gates are required.
+
+---
+
+## Roles
+
+| Role | Responsibility |
+|------|---------------|
+| **PM** (human) | Selects issues for the sprint, approves brainstorm (Gate 1), approves spec (Gate 2) |
+| **TL / Reviewer** (human) | Co-approves spec for technical decisions (Gate 2), reviews and approves the PR (Gate 3) |
+| **Claude** | Exploration, brainstorming, spec writing — acts on PM instruction via chat or via upstream label |
+| **Implementation Agent** | Implementation, running tests, opening the PR |
+| **Workflow** | All label swaps and card movements — the source of truth for board state |
+
+> **Principle:** Every board transition must be triggered by a GitHub event (label, PR, review) processed by a workflow. Agents must never be responsible for moving cards.
+
+---
+
+## Step-by-Step Flow
+
+### 💡 Idea
+Issue exists in the backlog with no `upstream:` label.
+
+---
+
+### 🔍 Exploration
+
+**Trigger (two equivalent paths):**
+- PM tells Claude directly in chat → Claude adds `upstream:exploration` to the issue, OR
+- PM adds `upstream:exploration` directly to the issue
+
+**Workflow:** `project-automation.yml` detects `upstream:exploration` → moves card to Exploration.
+
+**Who works:** Claude reads relevant code and context.
+
+---
+
+### 🧠 Brainstorming
+
+**Trigger:** Claude, after exploration.
+
+**Actions:**
+- Claude posts a comment on the issue with findings and 2–3 proposed approaches
+- Claude swaps `upstream:exploration` → `upstream:brainstorming`
+
+**Workflow:** `project-automation.yml` moves card to Brainstorming.
+
+**⏸ Human gate (Gate 1 — PM):** PM reads the brainstorming comment and selects an approach. This can be done:
+- By commenting on the issue (e.g., "Option A", "Go with B", "approved", "lgtm")
+- By telling Claude in chat
+
+**Note on implicit approval:** If Claude presented multiple options, selecting one (e.g., "Option A") counts as implicit approval. The `upstream-gate.yml` detects option-selection patterns in addition to explicit approval words.
+
+---
+
+### 📐 Detail Solution ← Gate 1
+
+**Trigger:** `upstream-gate.yml` detects PM approval comment on a `upstream:brainstorming` issue → swaps `upstream:brainstorming` → `upstream:detailing` via `PROJECT_TOKEN`.
+
+**Who works:** Claude rewrites the issue body with:
+1. User story (`As… I want… So that…`)
+2. Acceptance Criteria (AC1, AC2, …)
+3. Files to modify
+
+**After spec is written:** Claude swaps `upstream:detailing` → `upstream:approval`.
+
+**Workflow:** `project-automation.yml` moves card to Approval.
+
+---
+
+### ✅ Approval
+
+**⏸ Human gate (Gate 2 — PM + TL):** Both PM (business decisions) and TL (technical decisions) review the spec. When both are satisfied, PM adds label `spec:approved`.
+
+**Workflow:** `agent-trigger.yml` detects `spec:approved` →
+1. Removes `upstream:approval`
+2. Adds `upstream:development`
+3. Adds specific agent label (e.g., `jules`)
+4. Posts a structured comment with implementation instructions for the Agent
+
+**Workflow:** `project-automation.yml` moves card to Development.
+
+---
+
+### ⚙️ Development
+
+**Who works:** Implementation Agent implements the spec strictly within the Acceptance Criteria.
+
+**When done:** Agent adds `upstream:testing` before running tests.
+
+**Workflow:** `project-automation.yml` moves card to Testing.
+
+---
+
+### 🧪 Testing
+
+**Who works:** Agent runs the test suite (`vitest run` + `typecheck`).
+
+**When tests pass:** Agent opens a PR with `Closes #N` in the body.
+
+**Workflow:** `project-automation.yml` detects PR opened → moves linked issue to Code Review, adds `pr:in-review` label to the PR.
+
+---
+
+### 👁 Code Review ← Gate 3
+
+**⏸ Human gate (Gate 3 — TL / PM):** Reviewer reads the PR, verifies ACs, checks for regressions.
+
+**Trigger:** Reviewer approves the PR via GitHub's native review interface (no label needed).
+
+**Workflow:** `project-automation.yml` detects `pull_request_review: approved` → moves card to Production upon merge. Adds `pr:approved` label to the PR.
+
+---
+
+### 🚀 Production
+
+**Who acts:** PM or TL merges the PR.
+
+**Workflow:** `project-automation.yml` detects PR merged → moves card to Production.
+
+> **Note:** There is no separate "Merge" column. Review and merge happen in tight sequence in practice, and a transient column adds no visibility value.
+
+---
+
+## Label Reference
+
+| Label | Added by | Removed by |
+|-------|----------|------------|
+| `upstream:exploration` | PM (human) or Claude | Claude |
+| `upstream:brainstorming` | Claude | `upstream-gate.yml` |
+| `upstream:detailing` | `upstream-gate.yml` | Claude |
+| `upstream:approval` | Claude | `agent-trigger.yml` |
+| `upstream:development` | `agent-trigger.yml` | Impl. Agent |
+| `upstream:testing` | Impl. Agent | `project-automation.yml` (on PR open) |
+| `spec:approved` | PM (human) | — |
+| `agent_label` (e.g. `jules`, `sweep`) | `agent-trigger.yml` | — |
+| `pr:in-review` | `project-automation.yml` | `project-automation.yml` |
+| `pr:approved` | `project-automation.yml` | — |
+
+---
+
+## Human Gates Summary
+
+| Gate | Who | Trigger | What they decide |
+|------|-----|---------|-----------------|
+| **Gate 1** | PM | Comment on brainstorming issue | Which approach to pursue |
+| **Gate 2** | PM + TL | Add `spec:approved` label | Whether the spec is correct and complete |
+| **Gate 3** | TL / PM | GitHub PR review approval | Whether the implementation meets the ACs |
+
+---
+
+## Known Risk: Autonomous Agents and Informal Comments
+
+Implementation agents often monitor issue comments and can act on informal instructions (e.g., "@agent fix this") — bypassing Gates 1 and 2. This behavior is controlled by the agent's platform and cannot be prevented via GitHub Actions.
+
+**Mitigation:** The effective code quality gate is Gate 3 (PR review + mandatory CI). Never comment directly on issues to instruct the agent outside the `spec:approved` flow.
+
+See [issue #11](https://github.com/rafaeltcosta86/agentic-pdlc/issues/11) for full context.

package/docs/pdlc.md

@@ -72,7 +72,7 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | `stage:detailing` | Issue | Blue | Technical spec is being written |
 | `stage:development` | Issue | Orange | Agent is implementing the spec |
 | `spec:approved` | Issue | Green | Gate 2 — agent is cleared to implement |
-| `pr:review` | PR | Yellow | Awaiting code review |
+| `pr:in-review` | PR | Yellow | Awaiting code review |
 | `pr:approved` | PR | Green | Code review approved |
 
 ## Approval Gates

package/docs/spikes/04-upstream-flow-gap-analysis.md

@@ -0,0 +1,39 @@
+# Spike: Upstream Flow Gap Analysis
+
+This document analyzes the three gaps identified in the upstream flow of the Agentic PDLC framework and proposes solutions to ensure future projects receive these behaviors out of the box.
+
+## 1. Sprint start → cards move to Exploration automatically
+
+**Analysis:**
+Currently, when a PM selects issues for a sprint and tells the upstream agent to begin, the cards do not move automatically unless the agent explicitly runs a `gh issue edit` command.
+- `AGENTS.md` does not instruct the upstream agent to add `stage:exploration` (or equivalent) as its first action upon starting.
+- `project-automation.yml` does respond to the label `stage:exploration` and moves the card to the Exploration column.
+- The label naming convention (`stage:exploration`, `stage:brainstorming`, `stage:detailing`) is established in the workflow but not explicitly documented as a mandatory first step for the agent.
+
+**Solution (Gap):**
+- **Fix:** Update `AGENTS.md` and `adapters/claude-code/skill.md` to explicitly instruct the agent: *"When beginning work on a new issue, your first action must be to apply the `stage:exploration` label using the GitHub CLI."*
+
+## 2. Brainstorm gate — agent observes comments for PM approval
+
+**Analysis:**
+After the agent posts an exploration/brainstorming comment on the issue, it needs PM feedback (approval or requested changes) to proceed to Solution Detail.
+- There is no mechanism (webhook or workflow) for the upstream agent to automatically detect PM approval in an issue comment.
+- In current practice, the PM must manually notify the agent in the chat (e.g., "The brainstorm for #123 is approved").
+- This is a known limitation of current agent interfaces (which require explicit chat prompts to resume execution) and is not documented in the framework.
+
+**Solution (Gap):**
+- **Fix:** Acknowledge this limitation in the framework documentation. Update `SETUP.md` and/or a new `docs/workflow-guide.md` to establish the pattern: *"To pass Gate 1 (Brainstorming), the PM must review the issue comments and explicitly tell the agent in the chat to proceed to detailing for that specific issue."*
+
+## 3. spec:approved → implementation agent picks up the card
+
+**Analysis:**
+Cards in the "Approval" column wait for the PM to add the `spec:approved` label to signal the handoff to the implementation agent.
+- `agent-trigger.yml` correctly fires on the `spec:approved` label and comments on the issue to notify the implementation agent (e.g., Jules).
+- However, when `spec:approved` is added, `project-automation.yml` currently tries to move the card to `STATUS_APPROVAL` — which is the column it is already in.
+- The intent is for the card to move to "Development" when the handoff occurs.
+
+**Solution (Gap):**
+- **Fix:** Update `project-automation.yml`. In the `move-card-on-label` job, change the target status for `spec:approved` from `STATUS_APPROVAL` to `STATUS_DEVELOPMENT`.
+
+---
+*This analysis addresses the questions raised in Issue #4.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-pdlc",
-  "version": "1.2.1",
+  "version": "2.0.0",
   "description": "Scaffold the Agentic PDLC framework effortlessly",
   "type": "commonjs",
   "bin": {

package/templates/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# This file prevents autonomous agents from modifying core security, automation, and instruction rules
+# without explicit approval from the repository owner.
+
+.github/ @{{GITHUB_USERNAME}}
+AGENTS.md @{{GITHUB_USERNAME}}

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

@@ -12,8 +12,41 @@ jobs:
     # Runs only when spec:approved is added
     if: github.event.label.name == 'spec:approved'
     runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+      contents: read
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
-      - name: Comment on issue to trigger agent
+      - name: Update Labels
+        if: ${{ env.PROJECT_TOKEN != '' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.issue.number;
+            
+            try {
+              await github.rest.issues.removeLabel({
+                owner,
+                repo,
+                issue_number,
+                name: 'upstream:approval'
+              });
+            } catch (error) {
+              console.log('Label upstream:approval not found or could not be removed');
+            }
+            
+            await github.rest.issues.addLabels({
+              owner,
+              repo,
+              issue_number,
+              labels: ['upstream:development', '{{IMPLEMENTATION_AGENT_LABEL}}', 'agent:working']
+            });
+
+      - name: Comment on issue to trigger agent and prevent race conditions
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -22,6 +55,8 @@ jobs:
             const issueTitle = context.payload.issue.title;
 
             const body = [
+              `🤖 **Agentic PDLC Orchestrator:** I have dispatched the implementation agent. Please wait for the Pull Request and avoid making concurrent commits on this task to prevent race conditions.`,
+              '',
               `{{AGENT_HANDLE}} The spec for this issue has been approved. Please implement it exactly as described in the body above.`,
               '',
               '**Mandatory steps before you begin:**',
@@ -48,6 +83,10 @@ jobs:
     # Runs when architecture-violation is added (Sentinel flow)
     if: github.event.label.name == 'architecture-violation'
     runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+      contents: read
     steps:
       - name: Comment on issue to trigger agent
         uses: actions/github-script@v7

package/templates/.github/workflows/ci.yml

@@ -22,6 +22,9 @@ jobs:
       - name: Run Linters
         run: {{LINT_COMMAND}}
 
+      - name: Typecheck
+        run: {{TYPECHECK_COMMAND}}
+
       - name: Build
         run: {{BUILD_COMMAND}}
 

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

@@ -0,0 +1,123 @@
+name: PDLC Health Check (Drift Detection)
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 8 * * 1' # Every Monday at 8am
+
+env:
+  PROJECT_ID: "{{PROJECT_ID}}"
+  STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
+  STATUS_EXPLORATION: "{{ID_EXPLORATION}}"
+  STATUS_BRAINSTORMING: "{{ID_BRAINSTORMING}}"
+  STATUS_DETAILING: "{{ID_DETAILING}}"
+  STATUS_APPROVAL: "{{ID_APPROVAL}}"
+  STATUS_DEVELOPMENT: "{{ID_DEVELOPMENT}}"
+  STATUS_TESTING: "{{ID_TESTING}}"
+  STATUS_CODE_REVIEW_PR: "{{ID_CODE_REVIEW_PR}}"
+  STATUS_PRODUCTION: "{{ID_PRODUCTION}}"
+
+jobs:
+  check-drift:
+    name: Detect Project Board Drift
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+    permissions:
+      issues: write
+    steps:
+      - name: Validate Board Configuration
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const projectId = process.env.PROJECT_ID;
+            const statusFieldId = process.env.STATUS_FIELD_ID;
+            const envVars = {
+              'STATUS_EXPLORATION': process.env.STATUS_EXPLORATION,
+              'STATUS_BRAINSTORMING': process.env.STATUS_BRAINSTORMING,
+              'STATUS_DETAILING': process.env.STATUS_DETAILING,
+              'STATUS_APPROVAL': process.env.STATUS_APPROVAL,
+              'STATUS_DEVELOPMENT': process.env.STATUS_DEVELOPMENT,
+              'STATUS_TESTING': process.env.STATUS_TESTING,
+              'STATUS_CODE_REVIEW_PR': process.env.STATUS_CODE_REVIEW_PR,
+              'STATUS_PRODUCTION': process.env.STATUS_PRODUCTION
+            };
+
+            const query = `
+              query($projectId: ID!) {
+                node(id: $projectId) {
+                  ... on ProjectV2 {
+                    title
+                    fields(first: 20) {
+                      nodes {
+                        ... on ProjectV2SingleSelectField {
+                          id
+                          name
+                          options {
+                            id
+                            name
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            `;
+
+            let result;
+            try {
+              result = await github.graphql(query, { projectId });
+            } catch (error) {
+              console.log("❌ Error fetching project. Verify your PROJECT_ID.");
+              console.log(error);
+              return;
+            }
+
+            const project = result.node;
+            if (!project) {
+              console.log("❌ Project not found.");
+              return;
+            }
+
+            const statusField = project.fields.nodes.find(f => f.id === statusFieldId);
+            if (!statusField) {
+              console.log("❌ Status field not found.");
+              return;
+            }
+
+            const validOptions = statusField.options;
+            const validOptionIds = validOptions.map(o => o.id);
+
+            let hasDrift = false;
+            let missingVars = [];
+
+            for (const [varName, id] of Object.entries(envVars)) {
+              if (id && !id.startsWith('{{') && !validOptionIds.includes(id)) {
+                hasDrift = true;
+                missingVars.push(varName);
+              }
+            }
+
+            if (hasDrift) {
+              console.log("🚨 Drift detected! The following mapped columns no longer exist: " + missingVars.join(", "));
+              
+              let table = "| Column Name | New ID |\n|---|---|\n";
+              validOptions.forEach(opt => {
+                table += `| ${opt.name} | \`${opt.id}\` |\n`;
+              });
+
+              const body = `🚨 **Agentic PDLC Drift Detected**\n\nThe following columns mapped in your \`.github/workflows/project-automation.yml\` no longer exist in your project board:\n\n**${missingVars.join(", ")}**\n\n### How to fix it:\nHere is the list of current columns in your board with their valid IDs. Please update the \`env\` block in your \`.github/workflows/project-automation.yml\` and \`.github/workflows/pdlc-health-check.yml\`.\n\n${table}`;
+
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title: '🚨 Agentic PDLC Drift Detected in Project Board',
+                body: body,
+                labels: ['bug']
+              });
+            } else {
+              console.log("✅ No drift detected. Board configuration is healthy.");
+            }

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

@@ -16,9 +16,9 @@ env:
   STATUS_DETAILING: "{{ID_DETAILING}}"
   STATUS_APPROVAL: "{{ID_APPROVAL}}"
   STATUS_DEVELOPMENT: "{{ID_DEVELOPMENT}}"
+  STATUS_TESTING: "{{ID_TESTING}}"
   STATUS_CODE_REVIEW_PR: "{{ID_CODE_REVIEW_PR}}"
-  STATUS_MERGE: "{{ID_MERGE}}"
-  STATUS_PRODUCAO: "{{ID_PRODUCAO}}"
+  STATUS_PRODUCTION: "{{ID_PRODUCTION}}"
 
 jobs:
   # Issue Labeled → Move Upstream
@@ -39,21 +39,24 @@ jobs:
             let targetStatusId = null;
             let stageName = null;
 
-            if (labelName === 'stage:exploration') {
+            if (labelName === 'upstream:exploration') {
               targetStatusId = process.env.STATUS_EXPLORATION;
               stageName = 'Exploration';
-            } else if (labelName === 'stage:brainstorming') {
+            } else if (labelName === 'upstream:brainstorming') {
               targetStatusId = process.env.STATUS_BRAINSTORMING;
               stageName = 'Brainstorming';
-            } else if (labelName === 'stage:detailing') {
+            } else if (labelName === 'upstream:detailing') {
               targetStatusId = process.env.STATUS_DETAILING;
               stageName = 'Detailing';
-            } else if (labelName === 'spec:approved') {
+            } else if (labelName === 'upstream:approval') {
               targetStatusId = process.env.STATUS_APPROVAL;
               stageName = 'Approval';
-            } else if (labelName === 'stage:development') {
+            } else if (labelName === 'upstream:development') {
               targetStatusId = process.env.STATUS_DEVELOPMENT;
               stageName = 'Development';
+            } else if (labelName === 'upstream:testing') {
+              targetStatusId = process.env.STATUS_TESTING;
+              stageName = 'Testing';
             }
 
             if (!targetStatusId) {
@@ -83,6 +86,7 @@ jobs:
             await moveItem(node_id, targetStatusId);
             console.log(`Issue #${number} moved to ${stageName}`);
 
+{{OPTIONAL_ARCHITECTURE_VIOLATION_JOB}}
 
   # PR Opened → Move linked issue to Code Review / PR
   move-card-on-pr-open:
@@ -136,17 +140,17 @@ jobs:
               console.log(`PR #${prNumber} → Code Review / PR (no linked issue)`);
             }
 
-            await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:review'] }).catch(() => {});
+            await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:in-review'] }).catch(() => {});
 
-  # Review Approved → Merge
+  # Review Approved → Add Label
   move-card-on-review-approved:
-    name: Approved PR → Merge
+    name: Approved PR → Add Label
     if: github.event_name == 'pull_request_review' && github.event.review.state == 'approved'
     runs-on: ubuntu-latest
     env:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
-      - name: Move issue to Merge
+      - name: Swap PR labels
         if: ${{ env.PROJECT_TOKEN != '' }}
         uses: actions/github-script@v7
         with:
@@ -154,34 +158,7 @@ jobs:
           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 });
-            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_MERGE } });
-            };
-
-            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);
-              }
-            } else {
-              await moveItem(pr.node_id);
-            }
-
-            try { await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name: 'pr:review' }); } catch {}
+            try { await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name: 'pr:in-review' }); } catch {}
             await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:approved'] }).catch(() => {});
 
   # PR Merged → Production
@@ -215,7 +192,7 @@ jobs:
                     projectV2Item { id }
                   }
                 }`, { p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
-                      v: { singleSelectOptionId: process.env.STATUS_PRODUCAO } });
+                      v: { singleSelectOptionId: process.env.STATUS_PRODUCTION } });
             };
 
             if (linkedIssues.length > 0) {