|
| 1 | +/** |
| 2 | + * Fresh-repo `squad`/`squad:{agent}` label provisioning for `/squad plan activate` (#1955). |
| 3 | + * |
| 4 | + * `workflows/squad.md` promised `squad` and `squad:{agent}` labels on every issue the |
| 5 | + * activation flow creates, but the workflow only declared `issues: read` and a |
| 6 | + * `create-issue` safe-output — it never declared a way to create a label that does not |
| 7 | + * already exist. GitHub's REST API silently drops label names that are not already |
| 8 | + * present in the target repository when they're passed to `POST /issues`, so a |
| 9 | + * consumer's very first activation on a brand-new repo (zero pre-existing labels) |
| 10 | + * created every issue with none of the labels the docs promised. The old prose named |
| 11 | + * this honestly as a "prerequisite gap" instead of fixing it. |
| 12 | + * |
| 13 | + * The fix is gh-aw's `add-labels` safe output with `create-if-missing: true`: it creates |
| 14 | + * any label in its `allowed` list that the target repository is missing, then applies it |
| 15 | + * via an add-only GraphQL mutation. This suite locks in: |
| 16 | + * - the frontmatter no longer describes label creation as an unconfigured gap |
| 17 | + * - Steps 2b/2c call `add_labels` immediately after each verified `create-issue` result |
| 18 | + * - the roster-binding/correspondence/non-roster rules `gh-aw-agent-binding- |
| 19 | + * correspondence.test.ts` already locks in are untouched by this change |
| 20 | + * - the compiled workflow actually wires `create_if_missing: true` into the add_labels |
| 21 | + * safe-output handler config, so this isn't just unenforced prose |
| 22 | + * |
| 23 | + * Out of scope (per #1955's delegated task boundaries): running the E4 live end-to-end |
| 24 | + * test, and the `squad-plan-accept` fast-path's own separate create-issue/label logic |
| 25 | + * (only reachable when a flat `plan` artifact exists with no `program`/`implementation` |
| 26 | + * artifacts — see workflows/squad.md's `squad-plan-accept` skill). |
| 27 | + */ |
| 28 | + |
| 29 | +import { afterAll, describe, it, expect } from 'vitest'; |
| 30 | +import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'; |
| 31 | +import { execFileSync, spawnSync } from 'node:child_process'; |
| 32 | +import { join } from 'node:path'; |
| 33 | + |
| 34 | +const WORKFLOWS_DIR = join(process.cwd(), 'workflows'); |
| 35 | +const SQUAD_WORKFLOW = join(WORKFLOWS_DIR, 'squad.md'); |
| 36 | +const TEST_WORKSPACES_DIR = join(process.cwd(), '.test-workspaces-label-provisioning'); |
| 37 | + |
| 38 | +afterAll(() => { |
| 39 | + rmSync(TEST_WORKSPACES_DIR, { recursive: true, force: true }); |
| 40 | +}); |
| 41 | + |
| 42 | +/** Read a text file with line endings normalized to LF (Windows checkouts materialize CRLF). */ |
| 43 | +function readText(filePath: string): string { |
| 44 | + return readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n'); |
| 45 | +} |
| 46 | + |
| 47 | +const workflow = readText(SQUAD_WORKFLOW); |
| 48 | + |
| 49 | +/** Whitespace-collapsed view for prose assertions that may span wrapped lines. */ |
| 50 | +const prose = workflow.replace(/\s+/g, ' '); |
| 51 | + |
| 52 | +/** Isolate the `squad-plan-activate` skill body — the only in-scope command for #1955. */ |
| 53 | +const ACTIVATE_START = workflow.indexOf("## skill: `squad-plan-activate`"); |
| 54 | +const ACTIVATE_END = workflow.indexOf("## end skill: `squad-plan-activate`"); |
| 55 | +expect(ACTIVATE_START, '"## skill: `squad-plan-activate`" is missing from workflows/squad.md').toBeGreaterThan(-1); |
| 56 | +expect(ACTIVATE_END, '"## end skill: `squad-plan-activate`" is missing from workflows/squad.md').toBeGreaterThan(ACTIVATE_START); |
| 57 | +const activateSkill = workflow.slice(ACTIVATE_START, ACTIVATE_END); |
| 58 | +const activateProse = activateSkill.replace(/\s+/g, ' '); |
| 59 | + |
| 60 | +describe('gh-aw: fresh-repo label provisioning in squad-plan-activate (#1955)', () => { |
| 61 | + it('declares add-labels with create-if-missing in frontmatter, not a create-label safe-output', () => { |
| 62 | + // gh-aw has no `create-label` safe-output primitive; `add-labels` with |
| 63 | + // `create-if-missing: true` is the only supported mechanism. A regression here |
| 64 | + // (e.g. someone inventing `create-label`) would fail this assertion first. |
| 65 | + expect(workflow).toContain('add-labels:'); |
| 66 | + expect(workflow).toContain('create-if-missing: true'); |
| 67 | + expect(workflow).not.toContain('create-label:'); |
| 68 | + }); |
| 69 | + |
| 70 | + it('reframes the old "prerequisite gap" as solved, not still open', () => { |
| 71 | + // The phrase survives as a deliberate callback ("... is never a prerequisite gap"), |
| 72 | + // but the old admission that it was an unconfigured limitation must be gone. |
| 73 | + expect( |
| 74 | + /never a prerequisite gap/i.test(activateProse), |
| 75 | + 'The prose must state that a fresh repository with missing labels is no longer a ' + |
| 76 | + 'prerequisite gap now that add-labels/create-if-missing is declared.', |
| 77 | + ).toBe(true); |
| 78 | + |
| 79 | + expect( |
| 80 | + /not configured in this workflow/i.test(activateProse), |
| 81 | + 'The old "not configured in this workflow" admission must be removed along with ' + |
| 82 | + 'the gap it described.', |
| 83 | + ).toBe(false); |
| 84 | + }); |
| 85 | + |
| 86 | + it('documents that add-labels auto-provisions squad labels on a fresh repository', () => { |
| 87 | + expect( |
| 88 | + /`add-labels`.*`create-if-missing`.*auto-creates/is.test(activateSkill) || |
| 89 | + /create-if-missing.*creates any label/is.test(activateSkill), |
| 90 | + 'The Label Pre-flight section must explain that add-labels/create-if-missing ' + |
| 91 | + 'auto-provisions squad/squad:{agent} labels, replacing the removed gap language.', |
| 92 | + ).toBe(true); |
| 93 | + |
| 94 | + expect( |
| 95 | + /fresh repository/i.test(activateProse), |
| 96 | + 'The provisioning explanation should name the fresh-repository case #1955 reported.', |
| 97 | + ).toBe(true); |
| 98 | + }); |
| 99 | + |
| 100 | + it("explains why create-issue's own labels field cannot provision missing labels", () => { |
| 101 | + expect( |
| 102 | + /silently drops? label/i.test(activateProse), |
| 103 | + "The prose must state that create-issue's labels field cannot create missing " + |
| 104 | + 'labels — GitHub silently drops names that do not already exist — so a reader ' + |
| 105 | + "does not reintroduce reliance on create-issue's labels field alone.", |
| 106 | + ).toBe(true); |
| 107 | + }); |
| 108 | + |
| 109 | + it('calls add_labels immediately after create-issue for epics (2b)', () => { |
| 110 | + const epicAt = activateSkill.indexOf('**2b. Create Epic Issues:**'); |
| 111 | + const taskAt = activateSkill.indexOf('**2c. Create Task Issues:**'); |
| 112 | + expect(epicAt, '"**2b. Create Epic Issues:**" is missing').toBeGreaterThan(-1); |
| 113 | + expect(taskAt, '"**2c. Create Task Issues:**" is missing').toBeGreaterThan(epicAt); |
| 114 | + |
| 115 | + const epicSection = activateSkill.slice(epicAt, taskAt); |
| 116 | + expect( |
| 117 | + /add_labels/i.test(epicSection), |
| 118 | + 'Step 2b must call add_labels on the epic issue after create-issue returns.', |
| 119 | + ).toBe(true); |
| 120 | + expect( |
| 121 | + /verified/i.test(epicSection) && /add_labels/i.test(epicSection), |
| 122 | + 'The add_labels call must target the verified (real, returned) issue number, not a predicted one.', |
| 123 | + ).toBe(true); |
| 124 | + }); |
| 125 | + |
| 126 | + it('calls add_labels immediately after create-issue for tasks (2c), inside the atomic contract', () => { |
| 127 | + const taskAt = activateSkill.indexOf('**2c. Create Task Issues:**'); |
| 128 | + const selfValidationAt = activateSkill.indexOf('**2d. Self-Validation:**'); |
| 129 | + expect(taskAt, '"**2c. Create Task Issues:**" is missing').toBeGreaterThan(-1); |
| 130 | + expect(selfValidationAt, '"**2d. Self-Validation:**" is missing').toBeGreaterThan(taskAt); |
| 131 | + |
| 132 | + const taskSection = activateSkill.slice(taskAt, selfValidationAt); |
| 133 | + expect( |
| 134 | + /add_labels/i.test(taskSection), |
| 135 | + 'Step 2c must call add_labels on the task issue after create-issue returns.', |
| 136 | + ).toBe(true); |
| 137 | + |
| 138 | + const atomicAt = taskSection.indexOf('ATOMIC CONTRACT'); |
| 139 | + expect(atomicAt, '"ATOMIC CONTRACT" block is missing from Step 2c').toBeGreaterThan(-1); |
| 140 | + const atomicLine = taskSection.slice(atomicAt, atomicAt + 400); |
| 141 | + expect( |
| 142 | + /add_labels/i.test(atomicLine), |
| 143 | + 'The ATOMIC CONTRACT (one compose → one create-issue call → one verify) must be ' + |
| 144 | + 'extended to include the add_labels call, so the model cannot buffer multiple ' + |
| 145 | + 'tasks before labeling them.', |
| 146 | + ).toBe(true); |
| 147 | + }); |
| 148 | + |
| 149 | + it('never calls add_labels before create-issue has returned and been verified', () => { |
| 150 | + expect( |
| 151 | + /never call `add_labels` before/i.test(activateProse), |
| 152 | + 'The prose must explicitly forbid calling add_labels before create-issue has ' + |
| 153 | + 'returned a real issue number — there is nothing to target yet.', |
| 154 | + ).toBe(true); |
| 155 | + }); |
| 156 | + |
| 157 | + it('preserves the roster-binding correspondence rules unchanged (#1859, #1860)', () => { |
| 158 | + // This is a narrow smoke check; gh-aw-agent-binding-correspondence.test.ts is the |
| 159 | + // authoritative lock for these rules. This test only guards against this change |
| 160 | + // having silently damaged them while rewriting the surrounding label prose. |
| 161 | + expect(activateProse).toMatch(/own\s+`Agent`\s+cell/i); |
| 162 | + expect(activateProse).toMatch(/never inherit the parent epic/i); |
| 163 | + expect(activateProse).toMatch(/carry the previous task/i); |
| 164 | + expect(activateProse).toMatch(/two or more/i); |
| 165 | + expect(activateProse).toMatch(/never\s+choose\s+one\s+of\s+several/i); |
| 166 | + expect(activateProse).toMatch(/simultaneously certified and wrong/i); |
| 167 | + expect(activateProse).toMatch(/Non-roster agent values` heading is \*\*required\*\*/i); |
| 168 | + }); |
| 169 | + |
| 170 | + it('keeps rerun idempotency: reapplying labels on a rerun is a documented no-op', () => { |
| 171 | + expect( |
| 172 | + /re-applying an already-present label on a rerun is a no-op/i.test(activateProse), |
| 173 | + 'Rerun idempotency must be explicit: title-match dedup already skips recreating ' + |
| 174 | + 'issues, and add_labels must be safe to call again for issues that already carry ' + |
| 175 | + 'the label (add-only GraphQL merge semantics).', |
| 176 | + ).toBe(true); |
| 177 | + // Pre-existing idempotent-rerun contract (Step 2d) must remain intact. |
| 178 | + expect(activateProse).toMatch(/Re-runs are idempotent via title match/i); |
| 179 | + }); |
| 180 | + |
| 181 | + it('does not touch the separate squad-plan-accept fast-path label logic (out of scope)', () => { |
| 182 | + const acceptStart = workflow.indexOf('## skill: `squad-plan-accept`'); |
| 183 | + expect(acceptStart, '"## skill: `squad-plan-accept`" is missing from workflows/squad.md').toBeGreaterThan(-1); |
| 184 | + // squad-plan-accept has no "## end skill" marker of its own; its body runs until the |
| 185 | + // next "## skill:" heading (squad-plan-revise). |
| 186 | + const acceptEnd = workflow.indexOf('## skill: `squad-plan-revise`'); |
| 187 | + expect(acceptEnd, '"## skill: `squad-plan-revise`" is missing from workflows/squad.md').toBeGreaterThan(acceptStart); |
| 188 | + |
| 189 | + const acceptSkill = workflow.slice(acceptStart, acceptEnd); |
| 190 | + // #1955 is scoped to squad-plan-activate only; squad-plan-accept's own |
| 191 | + // create-issue/label fast path (reachable only for a flat plan with no |
| 192 | + // program/implementation artifacts) is intentionally unmodified here. |
| 193 | + expect(acceptSkill).not.toContain('add_labels'); |
| 194 | + expect(acceptSkill).not.toContain('create-if-missing'); |
| 195 | + }); |
| 196 | +}); |
| 197 | + |
| 198 | +// --------------------------------------------------------------------------- |
| 199 | +// Compiled-artifact verification |
| 200 | +// --------------------------------------------------------------------------- |
| 201 | +// |
| 202 | +// The assertions above lock the prose contract. This section proves the prose is |
| 203 | +// backed by a real, compilable safe-output: `gh aw compile --strict` must wire |
| 204 | +// `create_if_missing: true` into the add_labels handler config, and the add_labels |
| 205 | +// tool must be exposed to the agent. Fails closed (never skips) per this repo's |
| 206 | +// #1833/#1834 convention: an unmeasured contract is indistinguishable from a |
| 207 | +// violated one. |
| 208 | + |
| 209 | +const GH_AW_INSTALL_HINT = |
| 210 | + '`gh aw` is required to compile the workflow this gate inspects. Install it with ' + |
| 211 | + '`gh extension install github/gh-aw` (matches .github/workflows/squad-ci.yml). This ' + |
| 212 | + 'gate fails closed rather than skipping: an unmeasured contract is indistinguishable ' + |
| 213 | + 'from a violated one (#1834).'; |
| 214 | + |
| 215 | +describe('gh-aw: add-labels compiles into the real safe-output handler config (#1955)', () => { |
| 216 | + let compiledLock: string | null = null; |
| 217 | + |
| 218 | + function lockText(): string { |
| 219 | + if (compiledLock !== null) return compiledLock; |
| 220 | + |
| 221 | + const versionProbe = spawnSync('gh', ['aw', '--version'], { encoding: 'utf8' }); |
| 222 | + if (versionProbe.status !== 0) { |
| 223 | + throw new Error(`gh aw --version failed. ${GH_AW_INSTALL_HINT}`); |
| 224 | + } |
| 225 | + |
| 226 | + mkdirSync(TEST_WORKSPACES_DIR, { recursive: true }); |
| 227 | + const workspace = mkdtempSync(join(TEST_WORKSPACES_DIR, 'add-labels-')); |
| 228 | + execFileSync('git', ['init', '--quiet'], { cwd: workspace }); |
| 229 | + // gh-aw's dispatch-workflow validation resolves cross-workflow references against |
| 230 | + // a `.github/workflows/` directory located relative to the compiled file. This repo |
| 231 | + // ships the gh-aw *source* from a top-level `workflows/` dir; downstream consumers |
| 232 | + // install it into `.github/workflows/` via `gh aw add`. Mirror that real deployment |
| 233 | + // layout, matching .github/workflows/squad-ci.yml's own compile gate. |
| 234 | + cpSync(WORKFLOWS_DIR, join(workspace, '.github', 'workflows'), { recursive: true }); |
| 235 | + execFileSync('gh', ['aw', 'compile', '.github/workflows/squad.md', '--strict', '--approve', '--no-check-update'], { |
| 236 | + cwd: workspace, |
| 237 | + encoding: 'utf8', |
| 238 | + stdio: 'pipe', |
| 239 | + }); |
| 240 | + |
| 241 | + const lockPath = join(workspace, '.github', 'workflows', 'squad.lock.yml'); |
| 242 | + if (!existsSync(lockPath)) { |
| 243 | + throw new Error( |
| 244 | + `gh aw compile produced no squad.lock.yml — the compiled artifact this gate ` + |
| 245 | + `inspects is absent, so the contract is unmeasured. ${GH_AW_INSTALL_HINT}`, |
| 246 | + ); |
| 247 | + } |
| 248 | + compiledLock = readText(lockPath); |
| 249 | + return compiledLock; |
| 250 | + } |
| 251 | + |
| 252 | + it('strict-compiles with add-labels declared', () => { |
| 253 | + expect(lockText().length).toBeGreaterThan(0); |
| 254 | + }); |
| 255 | + |
| 256 | + it('wires create_if_missing: true and the allowed squad label patterns into the handler config', () => { |
| 257 | + // gh-aw v0.87.x (this fix's required pin bump) emits this JSON config only |
| 258 | + // embedded inside a double-quoted YAML env var value, with every `"` |
| 259 | + // backslash-escaped. De-escape before matching so this holds regardless of a |
| 260 | + // given compiler version's quoting choice. |
| 261 | + const compiled = lockText().replace(/\\"/g, '"'); |
| 262 | + expect(compiled).toContain('"add_labels"'); |
| 263 | + expect(compiled).toMatch(/"add_labels":\{[^}]*"create_if_missing":true/); |
| 264 | + expect(compiled).toMatch(/"add_labels":\{[^}]*"allowed":\["squad","squad:\*"\]/); |
| 265 | + }); |
| 266 | + |
| 267 | + it('exposes add_labels as a tool the agent can call, alongside create_issue', () => { |
| 268 | + const compiled = lockText(); |
| 269 | + expect(compiled).toMatch(/"tools":\[[^\]]*"add_labels"[^\]]*\]/); |
| 270 | + expect(compiled).toMatch(/"tools":\[[^\]]*"create_issue"[^\]]*\]/); |
| 271 | + }); |
| 272 | + |
| 273 | + it("does not broaden the main agent job's permissions — writes stay in the safe-output job", () => { |
| 274 | + const compiled = lockText(); |
| 275 | + const agentJobAt = compiled.indexOf('\n agent:\n'); |
| 276 | + const safeOutputsJobAt = compiled.indexOf('\n safe_outputs:\n'); |
| 277 | + expect(agentJobAt, '"agent:" job is missing from the compiled lock file').toBeGreaterThan(-1); |
| 278 | + expect(safeOutputsJobAt, '"safe_outputs:" job is missing from the compiled lock file').toBeGreaterThan(agentJobAt); |
| 279 | + |
| 280 | + const agentJob = compiled.slice(agentJobAt, safeOutputsJobAt); |
| 281 | + // The agent job's own permissions block (the first "permissions:" after the job |
| 282 | + // name) must remain issues: read — write access lives only in the safe_outputs job. |
| 283 | + const permsMatch = agentJob.match(/permissions:\n((?:\s{6}\S.*\n)+)/); |
| 284 | + expect(permsMatch, 'agent job permissions block not found').not.toBeNull(); |
| 285 | + const permsBlock = permsMatch ? permsMatch[1] : ''; |
| 286 | + expect(permsBlock).toContain('issues: read'); |
| 287 | + expect(permsBlock).not.toContain('issues: write'); |
| 288 | + }); |
| 289 | +}); |
0 commit comments