create-agentic-pdlc 2.4.0 → 3.1.0

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

@@ -1,39 +1,66 @@
 #!/bin/bash
-# PDLC Stage Gate — blocks gh pr create without stage:approval on linked issue.
+# PDLC Stage Gate — blocks gh pr create and file edits without spec:approved 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 "")
+FILE_PATH=$(echo "$INPUT" | node -e "const d=JSON.parse(require('fs').readFileSync(0)); console.log(d.file_path || '')" 2>/dev/null || echo "")
 
-if ! echo "$COMMAND" | grep -q "gh pr create"; then
+IS_PR_CREATE=false
+IS_FILE_EDIT=false
+
+if echo "$COMMAND" | grep -q "gh pr create"; then
+  IS_PR_CREATE=true
+elif [ -n "$FILE_PATH" ]; then
+  IS_FILE_EDIT=true
+fi
+
+if [ "$IS_PR_CREATE" != "true" ] && [ "$IS_FILE_EDIT" != "true" ]; 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
+  if [ "$IS_FILE_EDIT" = "true" ]; then
+    exit 0
+  fi
   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 "")
+LABELS=$(gh issue view "$ISSUE_NUM" --json labels --jq '[.labels[].name] | join(" ")' 2>/dev/null)
+if [ $? -ne 0 ] || [ -z "$LABELS" ]; then
+  echo "❌ PDLC Stage Gate: Could not fetch labels for issue #$ISSUE_NUM."
+  echo "   Missing condition: spec:approved"
+  echo "   Next step: verify gh auth and issue number, then have PM add spec:approved."
+  exit 1
+fi
 
-if echo "$LABELS" | grep -qw "stage:approval"; then
-  echo "✅ PDLC: Issue #$ISSUE_NUM approved — gate passed."
+if echo "$LABELS" | grep -qw "spec:approved"; then
   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 label on the issue."
-echo "   Emergency bypass: rename branch to hotfix/<issue-number>-<description>."
+
+if [ "$IS_PR_CREATE" = "true" ]; then
+  echo "❌ PDLC Stage Gate: PR creation blocked — issue #$ISSUE_NUM missing spec:approved."
+  echo "   Current stage: $STAGE"
+  echo "   Missing condition: spec:approved (set by PM after reviewing spec in issue body)"
+  echo "   Next step: complete spec → stage:approval → wait for PM to add spec:approved."
+  echo "   Emergency bypass: rename branch to hotfix/<issue-number>-<description>."
+else
+  echo "❌ PDLC Stage Gate: File edit blocked — issue #$ISSUE_NUM missing spec:approved."
+  echo "   Current stage: $STAGE"
+  echo "   Missing condition: spec:approved (set by PM after reviewing spec in issue body)"
+  echo "   Next step: complete spec → stage:approval → wait for PM to add spec:approved."
+  echo "   Emergency bypass: rename branch to hotfix/<issue-number>-<description>."
+fi
 exit 1

package/.claude/settings.json

@@ -9,6 +9,24 @@
             "command": "bash .agentic-pdlc/hooks/pdlc-stage-gate.sh"
           }
         ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .agentic-pdlc/hooks/pdlc-stage-gate.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .agentic-pdlc/hooks/pdlc-stage-gate.sh"
+          }
+        ]
       }
     ]
   }

package/.coderabbit.yaml

@@ -0,0 +1,41 @@
+language: "en-US"
+reviews:
+  profile: "assertive"
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  auto_review:
+    enabled: true
+    drafts: false
+    base_branches:
+      - main
+  path_instructions:
+    - path: "bin/cli.js"
+      instructions: >
+        All user-facing console.log strings must use the t() translation helper.
+        New strings must be added to the i18n object and referenced via i18n.key_name.
+        Flag any hardcoded English-only string in console output as a violation of
+        the project's i18n pattern.
+    - path: ".github/workflows/**"
+      instructions: >
+        Pay close attention to GitHub Actions syntax correctness, trigger
+        semantics (push/pull_request/workflow_run events and their filters),
+        expression syntax (${{ }}), and shell quoting in run steps.
+        Flag any logic that could cause silent failures or unintended trigger
+        behavior.
+  review_status: true
+  auto_apply_labels: true
+  labeling_instructions:
+    - label: "architecture-violation"
+      instructions: >
+        Apply when the PR introduces runtime behavior that violates documented
+        architectural invariants: code that bypasses the PDLC stage gate at runtime,
+        application code that programmatically sets or removes labels reserved for
+        automation (stage:*, spec:approved, qa:*) outside of their designated
+        automation workflows, business logic added directly to templates instead of
+        the CLI, or behavior that directly contradicts invariants in AGENTS.md or
+        CLAUDE.md. Do NOT apply for configuration changes to tools (e.g., updating
+        .coderabbit.yaml, GitHub Actions workflows, or CI config files) — those are
+        infrastructure, not invariant violations.
+chat:
+  auto_reply: true

package/.github/workflows/add-to-board.yml

@@ -4,21 +4,69 @@ on:
   issues:
     types: [opened]
 
-env:
-  PROJECT_ID: "PVT_kwHODpFFL84BXg7h"
-  STATUS_FIELD_ID: "PVTSSF_lAHODpFFL84BXg7hzhStRHI"
-  STATUS_IDEA: "bb6e5a20"
-
 jobs:
+  resolve-ids:
+    name: Resolve Board Column IDs
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+    outputs:
+      project_id: ${{ steps.resolve.outputs.project_id }}
+      status_field_id: ${{ steps.resolve.outputs.status_field_id }}
+      status_idea: ${{ steps.resolve.outputs.status_idea }}
+    steps:
+      - name: Resolve column IDs by name
+        id: resolve
+        if: ${{ env.PROJECT_TOKEN != '' && vars.PROJECT_ID != '' }}
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const projectId = '${{ vars.PROJECT_ID }}';
+            if (!projectId || projectId === '{{PROJECT_ID}}') {
+              core.warning('vars.PROJECT_ID not set — board features disabled');
+              return;
+            }
+            const { node } = await github.graphql(`
+              query($id: ID!) {
+                node(id: $id) {
+                  ... on ProjectV2 {
+                    fields(first: 20) {
+                      nodes {
+                        ... on ProjectV2SingleSelectField {
+                          id
+                          name
+                          options { id name }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            `, { id: projectId });
+            const statusField = node.fields.nodes.find(f => f.name === 'Status');
+            if (!statusField) { core.setFailed('Status field not found on board'); return; }
+            const opt = (name) => statusField.options.find(o => o.name.includes(name))?.id ?? '';
+            const ideaId = opt('Idea');
+            if (!ideaId) { core.setFailed('Required Status column "Idea" not found on board'); return; }
+            core.setOutput('project_id', projectId);
+            core.setOutput('status_field_id', statusField.id);
+            core.setOutput('status_idea', ideaId);
+            console.log('✅ Board IDs resolved by name');
+
   add-to-board:
     name: Auto-add new issue to board
+    needs: [resolve-ids]
     runs-on: ubuntu-latest
     env:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+      PROJECT_ID: ${{ needs.resolve-ids.outputs.project_id }}
+      STATUS_FIELD_ID: ${{ needs.resolve-ids.outputs.status_field_id }}
+      STATUS_IDEA: ${{ needs.resolve-ids.outputs.status_idea }}
     steps:
       - name: Add issue to project board
-        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v8
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |

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

@@ -7,9 +7,56 @@ on:
     types: [labeled]
 
 jobs:
+  resolve-ids:
+    name: Resolve Board Column IDs
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+    outputs:
+      project_id: ${{ steps.resolve.outputs.project_id }}
+      status_field_id: ${{ steps.resolve.outputs.status_field_id }}
+      status_development: ${{ steps.resolve.outputs.status_development }}
+    steps:
+      - name: Resolve column IDs by name
+        id: resolve
+        if: ${{ env.PROJECT_TOKEN != '' && vars.PROJECT_ID != '' }}
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const projectId = '${{ vars.PROJECT_ID }}';
+            if (!projectId || projectId === '{{PROJECT_ID}}') {
+              core.warning('vars.PROJECT_ID not set — board features disabled');
+              return;
+            }
+            const { node } = await github.graphql(`
+              query($id: ID!) {
+                node(id: $id) {
+                  ... on ProjectV2 {
+                    fields(first: 20) {
+                      nodes {
+                        ... on ProjectV2SingleSelectField {
+                          id
+                          name
+                          options { id name }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            `, { id: projectId });
+            const statusField = node.fields.nodes.find(f => f.name === 'Status');
+            if (!statusField) { core.setFailed('Status field not found on board'); return; }
+            const opt = (name) => statusField.options.find(o => o.name.includes(name))?.id ?? '';
+            core.setOutput('project_id', projectId);
+            core.setOutput('status_field_id', statusField.id);
+            core.setOutput('status_development', opt('Development'));
+            console.log('✅ Board IDs resolved by name');
+
   trigger-implementation-agent:
     name: Advance issue to stage:development
-    # Runs only when spec:approved is added
+    needs: [resolve-ids]
     if: github.event.label.name == 'spec:approved'
     runs-on: ubuntu-latest
     permissions:
@@ -17,40 +64,28 @@ jobs:
       contents: read
     env:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
-      PROJECT_ID: "PVT_kwHODpFFL84BXg7h"
-      STATUS_FIELD_ID: "PVTSSF_lAHODpFFL84BXg7hzhStRHI"
-      STATUS_DEVELOPMENT: "2c9e78e6"
+      PROJECT_ID: ${{ needs.resolve-ids.outputs.project_id }}
+      STATUS_FIELD_ID: ${{ needs.resolve-ids.outputs.status_field_id }}
+      STATUS_DEVELOPMENT: ${{ needs.resolve-ids.outputs.status_development }}
     steps:
       - name: Swap labels — stage:approval → stage:development
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           github-token: ${{ secrets.GITHUB_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: 'stage:approval'
-              });
+              await github.rest.issues.removeLabel({ owner, repo, issue_number, name: 'stage:approval' });
             } catch (error) {
               console.log('Label stage:approval not found or could not be removed');
             }
-
-            await github.rest.issues.addLabels({
-              owner,
-              repo,
-              issue_number,
-              labels: ['stage:development']
-            });
+            await github.rest.issues.addLabels({ owner, repo, issue_number, labels: ['stage:development'] });
 
       - name: Move board card to Development
-        if: ${{ env.PROJECT_TOKEN != '' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
         continue-on-error: true
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |
@@ -71,7 +106,6 @@ jobs:
 
   trigger-agent-on-violation:
     name: Flag architecture violation
-    # Runs when architecture-violation is added (Sentinel flow)
     if: github.event.label.name == 'architecture-violation'
     runs-on: ubuntu-latest
     permissions:
@@ -79,12 +113,11 @@ jobs:
       contents: read
     steps:
       - name: Comment on issue
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
             const issueNumber = context.payload.issue.number;
-
             const body = [
               `⚠️ **Architecture violation detected.** Please fix the issue described above.`,
               '',
@@ -96,7 +129,6 @@ jobs:
               '- Fix only what the violation points out — do not refactor unrelated code',
               `- Include \`Closes #${issueNumber}\` in the PR body`,
             ].join('\n');
-
             await github.rest.issues.createComment({
               owner: context.repo.owner,
               repo: context.repo.repo,

package/.github/workflows/board-reconciliation.yml

@@ -0,0 +1,176 @@
+name: Board Reconciliation (Drift Heal)
+
+on:
+  schedule:
+    - cron: '0 */6 * * *'
+  workflow_dispatch:
+
+jobs:
+  resolve-ids:
+    name: Resolve Board Column IDs
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+    outputs:
+      project_id: ${{ steps.resolve.outputs.project_id }}
+      status_field_id: ${{ steps.resolve.outputs.status_field_id }}
+      status_brainstorming: ${{ steps.resolve.outputs.status_brainstorming }}
+      status_detailing: ${{ steps.resolve.outputs.status_detailing }}
+      status_approval: ${{ steps.resolve.outputs.status_approval }}
+      status_development: ${{ steps.resolve.outputs.status_development }}
+      status_code_review_pr: ${{ steps.resolve.outputs.status_code_review_pr }}
+    steps:
+      - name: Resolve column IDs by name
+        id: resolve
+        if: ${{ env.PROJECT_TOKEN != '' && vars.PROJECT_ID != '' }}
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const projectId = '${{ vars.PROJECT_ID }}';
+            if (!projectId || projectId === '{{PROJECT_ID}}') {
+              core.warning('vars.PROJECT_ID not set — board features disabled');
+              return;
+            }
+            const { node } = await github.graphql(`
+              query($id: ID!) {
+                node(id: $id) {
+                  ... on ProjectV2 {
+                    fields(first: 20) {
+                      nodes {
+                        ... on ProjectV2SingleSelectField {
+                          id
+                          name
+                          options { id name }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            `, { id: projectId });
+            const statusField = node.fields.nodes.find(f => f.name === 'Status');
+            if (!statusField) { core.setFailed('Status field not found on board'); return; }
+            const opt = (name) => statusField.options.find(o => o.name.includes(name))?.id ?? '';
+            const ids = {
+              brainstorming:  opt('Brainstorming'),
+              detailing:      opt('Detailing'),
+              approval:       opt('Approval'),
+              development:    opt('Development'),
+              code_review_pr: opt('Code Review'),
+            };
+            const missing = Object.entries(ids).filter(([, v]) => !v).map(([k]) => k);
+            if (missing.length > 0) {
+              core.setFailed(`Required Status columns not found on board: ${missing.join(', ')}`);
+              return;
+            }
+            core.setOutput('project_id', projectId);
+            core.setOutput('status_field_id', statusField.id);
+            core.setOutput('status_brainstorming',  ids.brainstorming);
+            core.setOutput('status_detailing',      ids.detailing);
+            core.setOutput('status_approval',       ids.approval);
+            core.setOutput('status_development',    ids.development);
+            core.setOutput('status_code_review_pr', ids.code_review_pr);
+            console.log('✅ Board IDs resolved by name');
+
+  reconcile-board:
+    name: Reconcile Board (idempotent drift heal)
+    needs: [resolve-ids]
+    if: needs.resolve-ids.outputs.project_id != ''
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+      PROJECT_ID: ${{ needs.resolve-ids.outputs.project_id }}
+      STATUS_FIELD_ID: ${{ needs.resolve-ids.outputs.status_field_id }}
+      STATUS_BRAINSTORMING: ${{ needs.resolve-ids.outputs.status_brainstorming }}
+      STATUS_DETAILING: ${{ needs.resolve-ids.outputs.status_detailing }}
+      STATUS_APPROVAL: ${{ needs.resolve-ids.outputs.status_approval }}
+      STATUS_DEVELOPMENT: ${{ needs.resolve-ids.outputs.status_development }}
+      STATUS_CODE_REVIEW_PR: ${{ needs.resolve-ids.outputs.status_code_review_pr }}
+    steps:
+      - uses: actions/checkout@v5.0.1
+      - name: Reconcile all open board items
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const { classifyItem } = require('./scripts/derive-column.js');
+
+            const COLUMN_KEY_TO_ID = {
+              'code_review_pr': process.env.STATUS_CODE_REVIEW_PR,
+              'development':    process.env.STATUS_DEVELOPMENT,
+              'approval':       process.env.STATUS_APPROVAL,
+              'detailing':      process.env.STATUS_DETAILING,
+              'brainstorming':  process.env.STATUS_BRAINSTORMING,
+            };
+
+            // Paginate all board items
+            let allItems = [];
+            let cursor = null;
+            do {
+              const { node } = await github.graphql(`
+                query($id: ID!, $cursor: String) {
+                  node(id: $id) {
+                    ... on ProjectV2 {
+                      items(first: 50, after: $cursor) {
+                        pageInfo { hasNextPage endCursor }
+                        nodes {
+                          id
+                          fieldValueByName(name: "Status") {
+                            ... on ProjectV2ItemFieldSingleSelectValue { optionId }
+                          }
+                          content {
+                            ... on Issue {
+                              number
+                              state
+                              labels(first: 20) { nodes { name } }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              `, { id: process.env.PROJECT_ID, cursor });
+              const page = node.items;
+              allItems = allItems.concat(page.nodes);
+              cursor = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null;
+            } while (cursor);
+
+            let checked = 0, corrected = 0;
+
+            for (const item of allItems) {
+              // Skip PRs and closed issues
+              if (!item.content || item.content.state !== 'OPEN') continue;
+
+              const labelNames = item.content.labels.nodes.map(l => l.name);
+              const columnKey = classifyItem(labelNames);
+              if (!columnKey) continue; // no actionable label — skip (e.g. Idea column items)
+
+              const targetId = COLUMN_KEY_TO_ID[columnKey];
+              if (!targetId) continue; // column not resolved (shouldn't happen)
+
+              const currentId = item.fieldValueByName?.optionId ?? null;
+              checked++;
+
+              if (currentId === targetId) continue; // already correct — no mutation
+
+              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: targetId },
+              });
+
+              corrected++;
+              console.log(`Corrected #${item.content.number}: ${currentId ?? 'none'} → ${columnKey}`);
+            }
+
+            console.log(`✅ Reconciliation complete: ${checked} items checked, ${corrected} corrected`);