fix(workflows): target activation labels via gh-aw temporary IDs

[bradygaster]

Closes #1962
Parent #1957

Working as Procedures (Prompt Engineer) — issue carries squad:procedures.

Problem

The /squad plan activate prose instructed the model to read a real GitHub issue number back from each create-issue call, then target add_labels at that number:

After EVERY create-issue call: verify returned issue number, stop on failure, NEVER predict issue numbers.

gh-aw never returns an issue number to the agent. Issue creation is deferred to the post-agent safe-output job, so the agent only ever receives a success acknowledgement. The instruction was therefore unsatisfiable, and it left two failure modes:

1. The model either stalls waiting for a number that never arrives, or invents one.
2. An add_labels call whose item_number cannot be resolved does not error — it silently applies the labels to the triggering intent issue, branding the user's own request with an activated item's owner label.

Fix

Switched the full activation path to gh-aw's supported temporary_id linkage.

Area	Before	After
Frontmatter	create-issue accepted calls without a temp ID	require-temporary-id: true — a call without one is rejected
Hallucination Guard	"verify returned issue number"	States plainly that no number is returned; forbids predicting, inferring, or waiting
add_labels	targeted a "verified" real number	item_number = the minting create-issue call's temporary_id; a dedup-matched epic uses its verified real number
Task parent	implied the epic's real number	epic's #aw_epic{K} when minted this run; verified real number when 2b reused a deduped prior-phase epic
Dependency edges (Step 3)	blockedBy via write API with a real number	blocked_by declared on the create-issue call, using temporary IDs
Sub-issue fallback body ref	literal Parent: #{issue_number}	Parent: #aw_epic{K} when minted this run; verified real number otherwise
2d report_incomplete	"last verified issue number"	last task's temporary ID

New Temporary-ID Contract section covers:

• Form — the real gh-aw pattern ^#?aw_[A-Za-z0-9_]{3,12}$.
• Minting — derive, never invent — #aw_epic{K} (1-based epic position), #aw_task{N} (task's own # cell, non-alphanumerics → _, so 2.3 → #aw_task2_3). Overflow drops the epic/task word rather than truncating the number.
• Uniqueness is the prompt's responsibility — verified: gh-aw does not reject a duplicate temporary_id; temporaryIdMap.set() silently overwrites, so the last writer owns the mapping and earlier references resolve to the wrong issue. No warning is emitted.
• Explicit targeting is mandatory — names the silent-fallback hazard above.
• Existing and reused issues — targeted only by verified real numbers, since temporary IDs map only issues this run created.

Reused/deduped epics (review finding, fixed)

Step 2b dedups epics by title against prior phases. A reused epic was never minted in this run, so it has no entry in gh-aw's temporary-ID map — passing #aw_epic{K} for it would be an unresolvable reference. Both places that reference an epic now branch on provenance:

• Step 2c parent — temporary ID only when 2b minted the epic this run; verified real number for a dedup-by-title/prior-phase match. The prose also explicitly forbids passing a temporary ID that was not minted this run.
• Sub-issue Fallback body reference — same carve-out, and it matters more here: gh-aw leaves an unresolved #aw_… body reference verbatim rather than stripping it, so a temporary ID it never minted would ship to the user as a literal #aw_epic3.

Preserved unchanged: roster correspondence (per-task Agent cell, never inherited from the epic or carried forward), base squad, @copilot → squad:copilot, multi-owner epic behavior, non-roster recording, and origin-issue safety.

Contract verification (pinned gh-aw v0.87.10)

Checked against the binary's embedded schema and upstream source, not assumed:

• create_issue.temporary_id — optional string, ^#?aw_[A-Za-z0-9_]{3,12}$
• add_labels.item_number — number | string, ^(\d+|#?aw_[A-Za-z0-9_]{3,12})$
• create_issue.parent / create_issue.blocked_by — accept temporary IDs
• require-temporary-id: true compiles to "require_temporary_id":true, required_field_additions.create_issue: ["temporary_id"], and the agent-facing constraint string temporary_id is required.
• Ordering is safe: the topological sort inspects create_issue.blocked_by; an add_labels hitting an unresolved temp ID returns deferred and gets one retry pass — so create-issue then add_labels is the supported order.
• replaceTemporaryIdReferences() leaves an unresolved #aw_… body reference intact — the basis for the fallback carve-out above.

⚠️ Two things reviewers should confirm

1. require-temporary-id is workflow-global, not per-skill.

It is enforced in safe_outputs_handlers.cjs at the MCP tool layer from the single config.create_issue block. workflows/squad.md has a second create_issue caller — the squad-plan-accept fast path (#1959's scope) — whose calls would be rejected outright once the flag is on. I enabled the flag (an explicit #1962 success criterion) plus the smallest possible compliance edit to the fast path: mint a temporary ID and use it for parent. I deliberately did not add add_labels or create-if-missing there — that remains #1959, and an existing test asserts their absence in that region (still passing).

2. The Activation bindings: JSON block still references real issue numbers — and cannot be fixed here.

replaceTemporaryIdReferences() replaces an #aw_task1 token with `#${number}` — the # is retained for same-repo refs. Embedding #aw_ refs in that JSON code block would emit "issue": #42, which is invalid JSON. There is no substitution form that yields a bare number. Per the instruction to report rather than invent a workaround, I left the block unchanged and am flagging it as a blocker/decision for #1963 rather than papering over it. This means #1962's "no operation relies on an inferred issue number" is satisfied for every targeting operation but not yet for that reporting block.

Viable avenue for #1963: gh-aw exposes the resolved map as steps.process_safe_outputs.outputs.temporary_id_map (JSON { "aw_id": {"repo":..., "number":N} }) and as artifact /tmp/gh-aw/temporary-id-map.json.

Validation

• Strict compile: all 4 workflows (squad, squad-implement-worker, squad-review, squad-deps-worker) compile with --strict, all 4 lock files emitted, FAILED=0. Remaining warnings are pre-existing on dev (concurrency discriminator, slash_command+bots).
• Targeted tests: 296 passed across gh-aw-activation-temporary-ids, gh-aw-activation-label-provisioning, gh-aw-agent-binding-correspondence, gh-aw-activate-roster-binding, gh-aw-plan-lifecycle, gh-aw-quality.
• Build: npm run build passes.
• Full suite: 8127 passed. The 12 failures in cli-packaging-smoke / acceptance / external-state CLI tests are pre-existing — reproduced identically on the baseline with my changes stashed.

Test changes

Updated test/gh-aw-activation-label-provisioning.test.ts — one test asserted the prose must contain "never call add_labels before [create-issue] has returned a real issue number". That sentence encoded the exact invalid premise this issue corrects, so the test now asserts the inverse contract (the old rule is gone; the prose tells the model not to wait; create-issue returns no number).

Added test/gh-aw-activation-temporary-ids.test.ts (18 tests) — narrowly scoped to #1962: temporary-ID declaration on every activation create-issue, the documented gh-aw pattern, deterministic minting, the uniqueness mandate, mandatory explicit item_number, add_labels → temporary_id wiring, no-prediction rules, real numbers for reused issues, 2b/2c temp-ID fields, epic-as-parent, reused-epic parent targeting, sub-issue fallback provenance branching, blocked_by on create-issue, plus compiled-lock assertions that require_temporary_id actually reaches the handler config. Fails closed on a missing gh aw per the repo's #1834 convention.

Prose was tightened to stay under the existing 160 KB source-growth guard rather than raising it.

Out of scope (untouched)

/squad activate fast-path provisioning (#1959, beyond the minimal compliance edit above), activation reporting redesign (#1963), capacity safeguards (#1961), broad behavioral suite (#1960), E4 (#1958), checker distribution.

No changeset: no packages/*/src/ or templates/ changes, so the changelog-gate path regex does not match.

Note: #1964 conflicts at Step 2d. Not merged or rebased into this branch — the parent coordinator is sequencing integration.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit c95d43a

PR Scope: 🔧 Infrastructure

⚠️ 2 item(s) to address before review

Status	Check	Details
❌	Single commit	3 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	No source files changed — changeset not required
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	1 active Copilot thread(s) resolved (1 outdated skipped)
✅	CI passing	All checks passing

Files Changed (3 files, +436 −22)

File	+/−
test/gh-aw-activation-label-provisioning.test.ts	+20 −3
test/gh-aw-activation-temporary-ids.test.ts	+357 −0
workflows/squad.md	+59 −19

Total: +436 −22

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[github-actions]

🟡 Impact Analysis — PR #1965

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	3
Files added	1
Files modified	2
Files deleted	0
Modules touched	2

🎯 Risk Factors

• 3 files changed (≤5 → LOW)
• 2 modules touched (2-4 → MEDIUM)

📦 Modules Affected

root (1 file)

• workflows/squad.md

tests (2 files)

• test/gh-aw-activation-label-provisioning.test.ts
• test/gh-aw-activation-temporary-ids.test.ts

---

This report is generated automatically for every PR. See #733 for details.

[Copilot]

Copilot review overview

🟡 Changes recommended

The updated activation flow now applies labels via add_labels, but nearby workflow prose still contains inconsistent label-reporting and self-validation wording that can mislead the agent.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review tier: Lite
Findings: 2

New issues introduced by this change (2)

Severity	Finding
	workflows/​squad.md — Step 2d uses “requested/recognized” as the count being compared, but then tells the agent to call…
	workflows/​squad.md — This section now correctly instructs label application via add_labels targeting temporary_id,…

What changed in this PR

Updates the squad-plan-activate workflow contract to use gh-aw temporary_id linkage (instead of unsatisfiable “returned issue numbers”) so add_labels can deterministically target the intended created issues and avoid silent fallback labeling of the triggering intent issue.

Changes:

• Enforces require-temporary-id: true for create-issue safe outputs and documents a Temporary-ID Contract + hallucination guard updates.
• Rewrites activation label application instructions to target add_labels.item_number at the minting create-issue.temporary_id.
• Adds a focused contract test suite asserting both the prose contract and the compiled lock’s require_temporary_id wiring; updates the prior label-provisioning prose test accordingly.

File	Description
workflows/​squad.md	Requires temporary IDs for create-issue, updates activation contract to use temp IDs for parent/blocked_by/add_labels targeting, and refreshes hallucination guidance.
test/​gh-aw-activation-temporary-ids.test.ts	New tests asserting the temporary-ID contract in prose plus compiled-lock verification of require_temporary_id.
test/​gh-aw-activation-label-provisioning.test.ts	Updates an assertion to forbid the old “wait for returned issue number” contract and require the new “do not wait” language.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.