Skip to content

Commit babb595

Browse files
authored
Merge pull request #1956 from bradygaster/bradygaster-issue-1955-activation-label-provisioning
fix(gh-aw): auto-provision squad labels during plan activate
2 parents 6ce1221 + 993d026 commit babb595

10 files changed

Lines changed: 436 additions & 97 deletions

‎.github/workflows/squad-ci.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,7 @@ jobs:
173173
# than skipping — a skipped gate is indistinguishable from no gate. This
174174
# includes the shell input security contract gate (#1834) and the compile
175175
# contract (#1732).
176-
run: gh extension install --pin v0.86.2 github/gh-aw
176+
run: gh extension install --pin v0.87.10 github/gh-aw
177177
env:
178178
GH_TOKEN: ${{ github.token }}
179179
- name: Build
@@ -694,8 +694,8 @@ jobs:
694694
steps:
695695
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #v7
696696

697-
- name: Install gh-aw v0.86.2 (pinned)
698-
run: gh extension install --pin v0.86.2 github/gh-aw
697+
- name: Install gh-aw v0.87.10 (pinned)
698+
run: gh extension install --pin v0.87.10 github/gh-aw
699699
env:
700700
GH_TOKEN: ${{ github.token }}
701701

‎docs/src/content/docs/guide/gh-aw.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1168,7 +1168,7 @@ gh aw compile --strict
11681168
```
11691169
11701170
Confirm all four source files and generated locks reference `SQUAD_SHA`, review
1171-
the workflow diff, then commit them together. With gh-aw v0.86.2, do not use
1171+
the workflow diff, then commit them together. With gh-aw v0.87.10, do not use
11721172
`gh aw update` for this immutable-pin flow: its stored source branch and cooldown
11731173
can leave the installed sources at a different revision than the SHA you intend.
11741174
Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
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+
});

‎test/gh-aw-deps-routing.test.ts‎

Lines changed: 4 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import { execFileSync } from 'node:child_process';
44
import { tmpdir } from 'node:os';
55
import { basename, dirname, resolve } from 'node:path';
66
import { fileURLToPath } from 'node:url';
7+
import { extractSafeOutputsConfigJson } from './helpers/gh-aw-lock.js';
78

89
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
910
const WAVE_1_BASENAMES = new Set([
@@ -126,22 +127,9 @@ function compileSafeOutputs(workflowId: string): Record<string, Record<string, u
126127
);
127128

128129
const compiled = readFileSync(resolve(workflowDir, `${workflowId}.lock.yml`), 'utf8');
129-
const lines = compiled.split(/\r?\n/);
130-
const configStart = lines.findIndex(
131-
line => line.includes('/safeoutputs/config.json') && line.includes('<<'),
132-
);
133-
const delimiter = lines[configStart]?.match(/<< '([^']+)'/)?.[1];
134-
const configEnd = delimiter
135-
? lines.findIndex((line, index) => index > configStart && line.trim() === delimiter)
136-
: -1;
137-
138-
expect(configStart, `${workflowId} must compile safe-output config`).toBeGreaterThanOrEqual(0);
139-
expect(delimiter, `${workflowId} safe-output delimiter must be present`).toBeDefined();
140-
expect(configEnd, `${workflowId} safe-output config must terminate`).toBeGreaterThan(configStart);
141-
return JSON.parse(lines.slice(configStart + 1, configEnd).join('\n')) as Record<
142-
string,
143-
Record<string, unknown>
144-
>;
130+
const jsonText = extractSafeOutputsConfigJson(compiled);
131+
expect(jsonText, `${workflowId} must compile a parseable safe-output config`).toBeDefined();
132+
return JSON.parse(jsonText!) as Record<string, Record<string, unknown>>;
145133
}
146134

147135
describe('gh-aw dependency dispatcher routing (#1748 S3)', () => {

0 commit comments

Comments
 (0)