create-agentic-pdlc 3.0.0 → 3.1.0

package/bin/cli.js

@@ -60,6 +60,7 @@ const i18n = {
   cursor_rules_written: t('✅ Default cursor rules written to .cursorrules', '✅ Regras padrão do cursor salvas em .cursorrules', '✅ Reglas por defecto de cursor guardadas en .cursorrules'),
   setup_done: t('🎉 All set! Continue the setup with your agent:', '🎉 Aqui tá pronto! Continue o setup com o seu agente:', '🎉 ¡Listo! Continúa el setup con tu agente:'),
   setup_done_hint: t('>>> Tell it to read and execute the .agentic-setup.md file!', '>>> Diga a ele para ler e executar o arquivo .agentic-setup.md!', '>>> Dile que lea y ejecute el archivo .agentic-setup.md!'),
+  upgrade_hint: t('💡 To add the full board + multi-agent automation later: npx create-agentic-pdlc --upgrade-to-agentic', '💡 Para adicionar o board completo + automação multi-agente mais tarde: npx create-agentic-pdlc --upgrade-to-agentic', '💡 Para agregar el tablero completo + automatización multi-agente más tarde: npx create-agentic-pdlc --upgrade-to-agentic'),
   update_title: t('agentic-pdlc — Agent Configuration Status', 'agentic-pdlc — Status de Configuração dos Agentes', 'agentic-pdlc — Estado de Configuración de Agentes'),
   update_no_context: t('❌ No .agentic-pdlc/cli-context.json found. Run npx create-agentic-pdlc first.', '❌ Arquivo .agentic-pdlc/cli-context.json não encontrado. Rode npx create-agentic-pdlc primeiro.', '❌ Archivo .agentic-pdlc/cli-context.json no encontrado. Ejecuta npx create-agentic-pdlc primero.'),
   update_all_ok: t('All agents configured!', 'Todos os agentes configurados!', '¡Todos los agentes configurados!'),
@@ -80,6 +81,16 @@ const i18n = {
     '✅ Issue templates copiados para .github/ISSUE_TEMPLATE/',
     '✅ Issue templates copiados a .github/ISSUE_TEMPLATE/'
   ),
+  vars_project_id_ok: t(
+    '✅ vars.PROJECT_ID set as Actions Variable.',
+    '✅ vars.PROJECT_ID configurado como Variável do Actions.',
+    '✅ vars.PROJECT_ID configurado como Variable de Actions.'
+  ),
+  vars_project_id_warn: t(
+    '⚠️  Could not set vars.PROJECT_ID — token may lack variables:write scope.\n   Set manually: repo Settings → Secrets and variables → Variables → PROJECT_ID = ',
+    '⚠️  Não foi possível configurar vars.PROJECT_ID — o token pode não ter permissão variables:write.\n   Configure manualmente: repo Settings → Secrets and variables → Variables → PROJECT_ID = ',
+    '⚠️  No se pudo configurar vars.PROJECT_ID — el token puede no tener permiso variables:write.\n   Configura manualmente: repo Settings → Secrets and variables → Variables → PROJECT_ID = '
+  ),
 };
 
 const cyan = '\x1b[36m';
@@ -282,6 +293,29 @@ function scaffoldLiteTemplates(sourceDir, targetDir) {
   }
 }
 
+function setActionsVariable(repo, name, value, execFn = execFileSync) {
+  try {
+    execFn('gh', [
+      'api', `repos/${repo}/actions/variables/${name}`,
+      '--method', 'PATCH',
+      '-f', `name=${name}`,
+      '-f', `value=${value}`
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (err) {
+    const msg = (err.stderr?.toString() || '') + (err.message || '');
+    if (msg.includes('404') || msg.includes('Not Found')) {
+      execFn('gh', [
+        'api', `repos/${repo}/actions/variables`,
+        '--method', 'POST',
+        '-f', `name=${name}`,
+        '-f', `value=${value}`
+      ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    } else {
+      throw err;
+    }
+  }
+}
+
 function scaffoldFullTemplates(sourceDir, targetDir, projectId, statusFieldId, optionMap, repoOwner, repoName) {
   const destTemplates = path.join(targetDir, '.agentic-pdlc', 'templates');
   fs.mkdirSync(destTemplates, { recursive: true });
@@ -342,7 +376,6 @@ function scaffoldFullTemplates(sourceDir, targetDir, projectId, statusFieldId, o
   const paPath = path.join(destTemplates, '.github', 'workflows', 'project-automation.yml');
   if (fs.existsSync(paPath) && Object.keys(optionMap).length > 0) {
     let wfContent = fs.readFileSync(paPath, 'utf8');
-    if (projectId)     wfContent = wfContent.replace(/\{\{PROJECT_ID\}\}/g,      () => projectId);
     if (statusFieldId) wfContent = wfContent.replace(/\{\{STATUS_FIELD_ID\}\}/g, () => statusFieldId);
     wfContent = wfContent.replace(/\{\{ID_IDEA\}\}/g,                () => optionMap['💡 Idea - No move to Exploration directly'] || 'MISSING_ID');
     wfContent = wfContent.replace(/\{\{ID_EXPLORATION\}\}/g,         () => optionMap['🔍 Exploration']         || 'MISSING_ID');
@@ -536,21 +569,31 @@ async function runFullSetup() {
     }
   }
 
-  // Auto-provision PROJECT_PAT for personal repos
+  // Auto-provision PROJECT_TOKEN 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'] });
+        execFileSync('gh', ['secret', 'set', 'PROJECT_TOKEN', '--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}`);
+        console.log(`\n${green}✅ PROJECT_TOKEN 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}`);
+      console.log(`\n${yellow}⚠️  Could not auto-set PROJECT_TOKEN. 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}ℹ️  Org repo detected — PROJECT_TOKEN will require manual setup for security.${reset}`);
+  }
+
+  // Set PROJECT_ID as GitHub Actions Variable
+  if (projectId) {
+    try {
+      setActionsVariable(repo, 'PROJECT_ID', projectId);
+      console.log(`${green}${i18n.vars_project_id_ok}${reset}`);
+    } catch (_) {
+      console.log(`${yellow}${i18n.vars_project_id_warn}${projectId}${reset}`);
+    }
   }
 
   await setBranchProtection(repo, ['PDLC Stage Gate', 'QA Gate']);
@@ -790,7 +833,7 @@ function resolveMode(args) {
 }
 
 // Export for testing
-if (typeof module !== 'undefined') module.exports = { resolveMode };
+if (typeof module !== 'undefined') module.exports = { resolveMode, setActionsVariable, scaffoldLiteTemplates, scaffoldFullTemplates };
 
 // ─── runLiteSetup ─────────────────────────────────────────────────────────────
 
@@ -849,6 +892,7 @@ async function runLiteSetup() {
   });
 
   copyAdapterFiles(agent, sourceDir, targetDir);
+  console.log(`${cyan}${i18n.upgrade_hint}${reset}`);
 
   rl.close();
 }
@@ -988,20 +1032,30 @@ async function runUpgradeToAgentic() {
     }
   }
 
-  // Auto-provision PROJECT_PAT for personal repos
+  // Auto-provision PROJECT_TOKEN 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],
+        execFileSync('gh', ['secret', 'set', 'PROJECT_TOKEN', '--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}`);
+        console.log(`\n${green}✅ PROJECT_TOKEN secret set automatically (uses your gh OAuth token).${reset}`);
       }
     } catch (_) {
-      console.log(`\n${yellow}⚠️  Could not auto-set PROJECT_PAT. Agent will guide manual setup.${reset}`);
+      console.log(`\n${yellow}⚠️  Could not auto-set PROJECT_TOKEN. Agent will guide manual setup.${reset}`);
+    }
+  }
+
+  // Set PROJECT_ID as GitHub Actions Variable
+  if (projectId) {
+    try {
+      setActionsVariable(repo, 'PROJECT_ID', projectId);
+      console.log(`${green}${i18n.vars_project_id_ok}${reset}`);
+    } catch (_) {
+      console.log(`${yellow}${i18n.vars_project_id_warn}${projectId}${reset}`);
     }
   }
 

package/docs/superpowers/plans/2026-06-05-archive-card-on-issue-close.md

@@ -0,0 +1,105 @@
+# Archive Board Card on Issue Close Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Archive the GitHub Project board card when an issue is closed, preventing stale cards from accumulating in active columns.
+
+**Architecture:** Single new job appended to `project-automation.yml` template. Triggers on the already-present `issues: closed` event. Uses `addProjectV2ItemById` (idempotent) then `archiveProjectV2Item` — handles both issues closed without a PR and issues closed via PR merge safely.
+
+**Tech Stack:** GitHub Actions, `actions/github-script@v8`, GitHub GraphQL API (`addProjectV2ItemById`, `archiveProjectV2Item`).
+
+---
+
+## File Map
+
+| Action | Path | Responsibility |
+|---|---|---|
+| Modify | `templates/.github/workflows/project-automation.yml` | Add `move-card-on-issue-close` job at end of file |
+
+No unit tests — YAML workflow template; correctness verified by grep and manual inspection.
+
+---
+
+### Task 1: Add `move-card-on-issue-close` job
+
+**Files:**
+- Modify: `templates/.github/workflows/project-automation.yml` (append after `cleanup-labels-on-close`)
+
+- [ ] **Step 1: Verify the insertion point**
+
+Run:
+```bash
+tail -5 templates/.github/workflows/project-automation.yml
+```
+
+Expected: last line is `console.log(\`Issue #\${issue_number} labels cleaned up\`);` followed by closing braces. The file ends after `cleanup-labels-on-close`.
+
+- [ ] **Step 2: Append the new job**
+
+At the end of `templates/.github/workflows/project-automation.yml`, add:
+
+```yaml
+
+  move-card-on-issue-close:
+    name: Closed issue → Archive from board
+    if: github.event_name == 'issues' && github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+    steps:
+      - name: Archive board card
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const nodeId = context.payload.issue.node_id;
+            let itemId;
+            try {
+              const added = await github.graphql(`
+                mutation($p: ID!, $c: ID!) {
+                  addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+                }`, { p: process.env.PROJECT_ID, c: nodeId });
+              itemId = added.addProjectV2ItemById.item.id;
+            } catch (e) {
+              console.log(`Could not add issue to project: ${e.message}`);
+              return;
+            }
+            await github.graphql(`
+              mutation($p: ID!, $i: ID!) {
+                archiveProjectV2Item(input: {projectId: $p, itemId: $i}) { item { id } }
+              }`, { p: process.env.PROJECT_ID, i: itemId });
+            console.log(`Issue #${context.payload.issue.number} archived from board`);
+```
+
+- [ ] **Step 3: Verify job was added and file is syntactically correct**
+
+Run:
+```bash
+grep -n "move-card-on-issue-close\|archiveProjectV2Item" templates/.github/workflows/project-automation.yml
+```
+
+Expected: two matches — the job name line and the mutation name.
+
+Run:
+```bash
+python3 -c "import yaml, sys; yaml.safe_load(open('templates/.github/workflows/project-automation.yml'))" 2>&1
+```
+
+Expected: no output (valid YAML).
+
+- [ ] **Step 4: Verify guard condition matches existing pattern**
+
+Run:
+```bash
+grep "PROJECT_TOKEN != ''" templates/.github/workflows/project-automation.yml
+```
+
+Expected: multiple lines including the new job — confirms guard is consistent with other jobs.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add templates/.github/workflows/project-automation.yml
+git commit -m "feat(templates): archive board card when issue is closed"
+```

package/docs/superpowers/plans/2026-06-05-project-id-actions-variable.md

@@ -0,0 +1,336 @@
+# PROJECT_ID as Actions Variable Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace hardcoded `PROJECT_ID: "PVT_xxx"` in installed YAML files with `${{ vars.PROJECT_ID }}`, and have the installer set the value via the GitHub Actions Variables REST API.
+
+**Architecture:** Three workflow templates swap their `PROJECT_ID` env value and guard condition. `bin/cli.js` gains a `setActionsVariable(repo, name, value, execFn)` helper (dependency-injected `execFn` for testability) called after board creation in both the `runFullSetup` and `runUpgradeToAgentic` flows.
+
+**Tech Stack:** Node.js 22, `node:test` + `node:assert/strict`, `gh` CLI (`execFileSync`), GitHub Actions Variables REST API (`PATCH`/`POST /repos/{owner}/{repo}/actions/variables`).
+
+---
+
+## File Map
+
+| Action | Path | Responsibility |
+|---|---|---|
+| Modify | `templates/.github/workflows/project-automation.yml` | Remove `{{PROJECT_ID}}` placeholder, source from `vars` |
+| Modify | `templates/.github/workflows/add-to-board.yml` | Same |
+| Modify | `templates/.github/workflows/agent-trigger.yml` | Same |
+| Modify | `bin/cli.js` | Add helper, wire call sites, export helper |
+| Modify | `tests/cli.test.js` | Tests for `setActionsVariable` logic |
+
+---
+
+### Task 1: Update workflow templates
+
+**Files:**
+- Modify: `templates/.github/workflows/project-automation.yml`
+- Modify: `templates/.github/workflows/add-to-board.yml`
+- Modify: `templates/.github/workflows/agent-trigger.yml`
+
+No tests for template content — correctness is verified by the installer integration.
+
+- [ ] **Step 1: Replace `PROJECT_ID` env value in all three templates**
+
+In each of the three files, find every line matching:
+```yaml
+PROJECT_ID: "{{PROJECT_ID}}"
+```
+Replace with:
+```yaml
+PROJECT_ID: ${{ vars.PROJECT_ID }}
+```
+
+`project-automation.yml` line 12, `add-to-board.yml` line 8, `agent-trigger.yml` line 21.
+
+- [ ] **Step 2: Replace guard conditions in all three templates**
+
+In each of the three files, find every line matching:
+```yaml
+env.PROJECT_ID != '{{PROJECT_ID}}'
+```
+Replace with:
+```yaml
+env.PROJECT_ID != ''
+```
+
+Do a full-file search in each — there are multiple occurrences per file (every job that conditionally runs).
+
+- [ ] **Step 3: Verify no `{{PROJECT_ID}}` remains in workflow files**
+
+Run:
+```bash
+grep -rn "{{PROJECT_ID}}" templates/.github/workflows/
+```
+
+Expected: no output. If any lines appear, fix them before proceeding.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add templates/.github/workflows/project-automation.yml \
+        templates/.github/workflows/add-to-board.yml \
+        templates/.github/workflows/agent-trigger.yml
+git commit -m "feat(templates): source PROJECT_ID from vars instead of hardcoded placeholder"
+```
+
+---
+
+### Task 2: Remove `{{PROJECT_ID}}` YAML substitution from `scaffoldFullTemplates`
+
+**Files:**
+- Modify: `bin/cli.js:345`
+
+- [ ] **Step 1: Delete the single PROJECT_ID substitution line**
+
+In `bin/cli.js`, find and remove exactly this line (currently line 345):
+```javascript
+    if (projectId)     wfContent = wfContent.replace(/\{\{PROJECT_ID\}\}/g,      () => projectId);
+```
+
+The block around it (lines 342–356) substitutes `STATUS_FIELD_ID` and all `ID_*` column options into `project-automation.yml`. Keep all those lines. Only the `PROJECT_ID` line is removed.
+
+- [ ] **Step 2: Verify other substitutions are intact**
+
+Run:
+```bash
+grep -n "wfContent.replace" bin/cli.js
+```
+
+Expected output must include lines for `STATUS_FIELD_ID`, `ID_IDEA`, `ID_BRAINSTORMING`, `ID_DETAILING`, `ID_APPROVAL`, `ID_DEVELOPMENT`, `ID_TESTING`, `ID_CODE_REVIEW_PR`, `ID_PRODUCTION`. Must NOT include `PROJECT_ID`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add bin/cli.js
+git commit -m "fix(cli): remove PROJECT_ID hardcoding from scaffoldFullTemplates"
+```
+
+---
+
+### Task 3: Add `setActionsVariable` helper (TDD)
+
+**Files:**
+- Modify: `bin/cli.js` (add function before `scaffoldFullTemplates`, ~line 283)
+- Modify: `tests/cli.test.js` (add describe block)
+- Modify: `bin/cli.js:793` (add to `module.exports`)
+
+- [ ] **Step 1: Write failing tests**
+
+Add to `tests/cli.test.js`:
+
+```javascript
+const { describe, it, mock } = require('node:test');
+
+// ... existing imports and tests above ...
+
+describe('setActionsVariable', () => {
+  it('calls PATCH first', () => {
+    const calls = [];
+    const execFn = (cmd, args) => { calls.push(args); };
+    const { setActionsVariable } = require('../bin/cli.js');
+    setActionsVariable('owner/repo', 'PROJECT_ID', 'PVT_abc', execFn);
+    assert.equal(calls.length, 1);
+    assert.ok(calls[0].includes('--method'));
+    assert.ok(calls[0].includes('PATCH'));
+    assert.ok(calls[0].some(a => a.includes('PROJECT_ID')));
+  });
+
+  it('falls back to POST on 404', () => {
+    const calls = [];
+    let callCount = 0;
+    const execFn = (cmd, args) => {
+      calls.push([...args]);
+      callCount++;
+      if (callCount === 1) {
+        const err = new Error('Not Found');
+        err.stderr = Buffer.from('Not Found');
+        throw err;
+      }
+    };
+    const { setActionsVariable } = require('../bin/cli.js');
+    setActionsVariable('owner/repo', 'PROJECT_ID', 'PVT_abc', execFn);
+    assert.equal(calls.length, 2);
+    assert.ok(calls[0].includes('PATCH'));
+    assert.ok(calls[1].includes('POST'));
+  });
+
+  it('throws on 403', () => {
+    const execFn = () => {
+      const err = new Error('Forbidden');
+      err.stderr = Buffer.from('Forbidden');
+      throw err;
+    };
+    const { setActionsVariable } = require('../bin/cli.js');
+    assert.throws(
+      () => setActionsVariable('owner/repo', 'PROJECT_ID', 'PVT_abc', execFn),
+      /Forbidden/
+    );
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+npm test
+```
+
+Expected: 3 new test failures — `setActionsVariable` is not exported yet.
+
+- [ ] **Step 3: Add `setActionsVariable` to `bin/cli.js`**
+
+Insert this function before `scaffoldFullTemplates` (~line 283):
+
+```javascript
+function setActionsVariable(repo, name, value, execFn = execFileSync) {
+  try {
+    execFn('gh', [
+      'api', `repos/${repo}/actions/variables/${name}`,
+      '--method', 'PATCH',
+      '-f', `name=${name}`,
+      '-f', `value=${value}`
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (err) {
+    const msg = (err.stderr?.toString() || '') + (err.message || '');
+    if (msg.includes('404') || msg.includes('Not Found')) {
+      execFn('gh', [
+        'api', `repos/${repo}/actions/variables`,
+        '--method', 'POST',
+        '-f', `name=${name}`,
+        '-f', `value=${value}`
+      ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    } else {
+      throw err;
+    }
+  }
+}
+```
+
+- [ ] **Step 4: Export the function**
+
+In `bin/cli.js` at line 793, update:
+```javascript
+if (typeof module !== 'undefined') module.exports = { resolveMode };
+```
+to:
+```javascript
+if (typeof module !== 'undefined') module.exports = { resolveMode, setActionsVariable };
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+```bash
+npm test
+```
+
+Expected: all tests pass including the 3 new `setActionsVariable` tests.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add bin/cli.js tests/cli.test.js
+git commit -m "feat(cli): add setActionsVariable helper with PATCH→POST fallback"
+```
+
+---
+
+### Task 4: Wire `setActionsVariable` into the create flow (`runFullSetup`)
+
+**Files:**
+- Modify: `bin/cli.js` (~line 554)
+
+- [ ] **Step 1: Add the call site after the PROJECT_PAT block**
+
+In `bin/cli.js`, locate the end of the `PROJECT_PAT` block in `runFullSetup` (the `} else if (projectId && isOrg)` line at ~554). Add after it:
+
+```javascript
+  // Set PROJECT_ID as GitHub Actions Variable
+  if (projectId) {
+    try {
+      setActionsVariable(repo, 'PROJECT_ID', projectId);
+      console.log(`${green}✅ vars.PROJECT_ID set as Actions Variable.${reset}`);
+    } catch (_) {
+      console.log(`${yellow}⚠️  Could not set vars.PROJECT_ID — token may lack variables:write scope.\n   Set manually: repo Settings → Secrets and variables → Variables → PROJECT_ID = ${projectId}${reset}`);
+    }
+  }
+```
+
+Insert this block between line 554 (`} else if (projectId && isOrg) { ... }`) and line 556 (`await setBranchProtection(...)`).
+
+- [ ] **Step 2: Verify placement**
+
+```bash
+grep -n "vars.PROJECT_ID\|setBranchProtection\|isOrg\)" bin/cli.js | head -20
+```
+
+The `vars.PROJECT_ID` console log should appear between the `isOrg` block and `setBranchProtection`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add bin/cli.js
+git commit -m "feat(cli): set vars.PROJECT_ID as Actions Variable in create flow"
+```
+
+---
+
+### Task 5: Wire `setActionsVariable` into the upgrade flow (`runUpgradeToAgentic`)
+
+**Files:**
+- Modify: `bin/cli.js` (~line 1006)
+
+- [ ] **Step 1: Add the call site after the PROJECT_PAT block in the upgrade flow**
+
+In `bin/cli.js`, locate the end of the `PROJECT_PAT` block in `runUpgradeToAgentic` (the closing `}` of `if (projectId && !isOrg)` at ~line 1006). Add after it:
+
+```javascript
+  // Set PROJECT_ID as GitHub Actions Variable
+  if (projectId) {
+    try {
+      setActionsVariable(repo, 'PROJECT_ID', projectId);
+      console.log(`${green}✅ vars.PROJECT_ID set as Actions Variable.${reset}`);
+    } catch (_) {
+      console.log(`${yellow}⚠️  Could not set vars.PROJECT_ID — token may lack variables:write scope.\n   Set manually: repo Settings → Secrets and variables → Variables → PROJECT_ID = ${projectId}${reset}`);
+    }
+  }
+```
+
+Insert between line ~1006 (`}` closing the `PROJECT_PAT` block) and line ~1008 (`console.log scaffolding`).
+
+- [ ] **Step 2: Verify no `{{PROJECT_ID}}` placeholder survives install**
+
+```bash
+grep -rn "{{PROJECT_ID}}" templates/
+```
+
+Expected: only `templates/full/docs/pdlc.md` (the documentation file). No workflow YAML files.
+
+- [ ] **Step 3: Run full test suite**
+
+```bash
+npm test
+```
+
+Expected: all tests pass.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add bin/cli.js
+git commit -m "feat(cli): set vars.PROJECT_ID as Actions Variable in upgrade flow"
+```
+
+---
+
+## Self-Review Checklist
+
+- Acceptance Criteria 1 (new install sets `vars.PROJECT_ID`): Task 4 ✓
+- Acceptance Criteria 2 (`resolve-ids` works without YAML modification): Task 1 ✓
+- Acceptance Criteria 3 (`--update` sets variable): Task 5 ✓
+- Acceptance Criteria 4 (403 warning, non-fatal): Tasks 3, 4, 5 ✓
+- Edge case — PATCH first, POST on 404: Task 3 ✓
+- Edge case — `vars.PROJECT_ID` unset resolves to `''`, guard works: Task 1 ✓
+- No `{{PROJECT_ID}}` in any YAML after install: Tasks 1 + 2 ✓
+- All other ID substitutions preserved: Task 2 Step 2 ✓