fix(gh-aw): bound activation label capacity and make truncation explicit (#1961)

[bradygaster]

Closes #1961
Parent #1957

Working as FIDO (Quality Owner)

Revised after independent review. The first commit (adb718b2) made three factually wrong claims about the pinned gh-aw runtime. Commit ef5f2de2 corrects them against the v0.87.10 sources. The Corrections section records what changed and why, and the retracted claims now have negative-guard tests so they cannot come back.

Problem

An activation could label fewer issues than it created and still report a clean success. Two things made that possible: add-labels: max: 80 sat below the worst-case label-name count for a full activation, and nothing compared "issues activated" against "issues labeled" before the summary was written.

Capacity derivation

The largest activation supported in one run is 50 issues — the enterprise profile's max_issues: 50 (the highest documented profile limit), which is also the threshold the workflow's own phased-activation rule enforces.

Safe output	Worst case at 50 issues	max
create-issue	50 — one per epic/task	75 (unchanged)
add_labels	50 — one per created issue	110 (was 80)
Labels within one add_labels call	2 — squad + squad:{agent}	not capped by max
Label names across the whole run	100 — 50 × 2	110

Why 110 and not 80. max counts safe-output items (tool calls), so 50 calls never actually exhausted a cap of 80 — there was no runtime overflow. The real hazard is what gh-aw injects into the prompt: it renders the cap as "Maximum 80 label(s) can be added", which reads as a budget of label names, against a worst case of 100 names. An agent that believes it has 80 names for 100 names' worth of work rations them and self-truncates. 110 satisfies the worst case under both readings — 50 calls and 100 names — so neither interpretation can justify skipping a label operation. The margin stays bounded (a test caps it at 2× worst case) so this doesn't trade a silent-truncation bug for an unbounded-write one.

Safeguards

Frontmatter — add-labels: max 80 → 110, with a comment recording the derivation and pointing at the full analysis.

squad-plan-activate prose — the capacity table above, plus two corrected statements of runtime behaviour:

• max limits items, not label names; a two-label call costs one unit of budget.
• Reaching a cap is enforced twice, and neither layer fails the run (see Corrections feat: GitHub Issues intake, PRD mode, and human team members #2).

New Step 2e — Label-Operation Reconciliation. The agent keeps two counts while Steps 2b/2c run: activated and labeled. A call that was never made, was rejected, or errored counts as unlabeled.

• labeled == activated → complete, proceed.
• labeled < activated → call report_incomplete naming the shortfall and listing every affected work item.

For items created this run, the report names the stable temporary ID plus title and intended labels — not a GitHub issue number. Issue creation is deferred to the post-agent job, so no real number exists during the agent turn; a real number is quoted only for an issue that already existed and was recognized. Never predict, infer, or invent a number. (Added per the PR #1965 review, to avoid reintroducing #1962's invalid-number assumption.)

Reconciliation keys on absence of success, never on presence of an error — a call can simply never be made, and a surplus item is dropped at collection time with only a warning.

Step 2d — an existing sentence that let the agent guess a cap as the cause of a partial run now requires the cap to have been observed in Step 2e.

Corrections after review

All three verified directly against githubnext/gh-aw@v0.87.10, the CI pin.

1. report_incomplete does not make the run conclude non-successfully. report_incomplete_handler.cjs emits core.warning only. handle_agent_failure.cjs contains zero setFailed/process.exit calls across 4453 lines. What it actually does is open or update a durable [aw] {workflow} reported incomplete result tracking issue or comment. gh-aw's own tool description — "treated as a failure signal even when the agent exits successfully" — is misleading, and the first commit trusted it. Trusting injected prose over the runtime contract is precisely the failure mode #1961 exists to prevent.

Stated limitation. No narrow mechanism in the pinned runtime makes an incomplete activation conclude red. Forcing one would mean adding a custom safe-job, which is outside this issue's scope. #1961's criterion asks for "an explicit incomplete/failure result", and the durable tracking record satisfies that — but the run stays green, and the workflow now says so plainly so no future author assumes otherwise: "never rely on a red run to carry the signal."

2. Cap enforcement is dual. Per Safe Outputs spec MCE4, enforcePerTypeMax in safe_outputs_handlers.cjs throws JSON-RPC E002: {type} limit reached — {n} of {max} already used this run at invocation time (live for us, since getExplicitMax only applies when max is explicitly configured). The collector then drops surplus items with a warning. The claim that an over-limit item "never appears as an error to the agent" was wrong and is removed. Absence-of-success reconciliation is retained regardless, and the prose now warns that the absence of an E002 is not proof every label landed.

3. The 110 rationale is the injected wording, not a proven overflow. The first commit implied 50 calls could overflow a cap of 80. They cannot. The docblock now carries an explicit "Note what is not claimed" paragraph recording this.

Tests

New test/gh-aw-activation-capacity.test.ts — 28 tests. Prefers compiled/runtime evidence over prose: the boundary tests read the compiled .lock.yml safe-outputs config, so a frontmatter edit that fails to compile is caught.

• Cap derivation from the documented 50-issue maximum, both readings.
• Boundary: at max (50) everything fits; one-over (51) exceeds the documented maximum and must route to phased activation.
• Margin is bounded (≤ 2× worst case).
• Compiled config agrees with frontmatter.
• Step 2e contract: both counts, the labeled < activated branch, absence-of-success semantics, the temporary-ID rule, and the false-success prohibition.
• Two negative guards that fail if either retracted claim is reintroduced.

Mutation-checked, not just green:

Mutation	Result
max: 110 → 80	5 tests fail, including the compiled-runtime one
Reintroduce "never appears as an error to the agent"	guard fails
Reintroduce "failure signal even when the agent exits successfully"	guard fails
Step 2e demands a real issue number	temporary-ID test fails

Validation

• test/gh-aw-activation-capacity.test.ts, test/gh-aw-quality.test.ts, test/gh-aw-activation-label-provisioning.test.ts → 221/221 passing
• Strict compile clean on all four workflows (squad, squad-review, squad-implement-worker, squad-deps-worker); only the two pre-existing squad.md warnings remain
• npm run build passes
• Prose kept tight; the source-growth guard raise is disclosed and justified below rather than hidden

Scope

No permission changes — add-labels keeps its existing least-privileged grant; only max moved.

Deliberately untouched: temporary-ID linkage (#1962 / PR #1965), fast-path parity (#1959), label-result reporting beyond the explicit overflow path (#1963), broad contract coverage (#1960), E4 (#1958), checker distribution.

Integration note — this PR is stacked on #1965

Base is bradygaster-plan-activate-temporary-ids (PR #1965), not dev. #1965 head 528ba9b0 is merged into this branch (merge commit 8cbf9907, no force-push), so this PR reviews as a clean delta on top of the temporary-ID contract. Merge #1965 first, then this one; the base retargets to dev automatically when #1965 lands.

git merge-base 528ba9b0 HEAD == 528ba9b0, and the diff against the new base is 3 files — this PR contains no #1965 content, and nothing from #1966/#1963.

The one conflict (Step 2d) was resolved deliberately. #1965's Self-Validation sentence is taken wholesale — it is strictly stronger than this branch's version ("requested/recognized", "the last task's temporary ID", "never substitute a guessed issue number"). Only this PR's minimal trailing clause is reapplied, which is #1961's concern and unaddressed by #1965: never surface a safe-output cap as a guessed reason for a partial run — name a cap only when Step 2e observed one being reached.

Step 2e now targets #1965's real mechanism rather than forward-referencing it. The report identifier for an item created this run is the temporary_id minted under the Temporary-ID Contract (#aw_epic{K} / #aw_task{N}) — not an issue number, because creation is deferred to the safe-output job. A real number may be quoted only where independently verified (dedup-by-title match, or Step 1's idempotent-rerun path). This mirrors #1965's own "Existing and reused issues" rule instead of restating a parallel contract, so #1962's invalid-number assumption is not reintroduced.

Disclosed third-file change

test/gh-aw-quality.test.ts raises the source-growth guard 170 → 172 KB. This is a stacking consequence, not #1961 scope creep, and it follows that guard's own documented criterion rather than silencing a red test. The value was measured on the resolved branch, not guessed:

• Combined source measures 173 241 B (169.2 KB) — workflows/squad.md (118 258 B) plus its four imports.
• The canonical budget — "keeps the ambient prompt under 40 KB" — measures 32 795 B (32.0 KB), unchanged by Provision labels correctly in the recommended Squad activation fast path #1959/Use gh-aw temporary IDs for plan activation label targeting #1962/Prevent silent truncation of Squad activation label operations #1961 because all growth sits inside inline ## skill: blocks that gh-aw strips from the always-loaded prompt. The guard's own failure message names this as exactly when a raise is legitimate.
• Why not simply take dev's 170? It passes by only 839 bytes. That is the same stale-threshold failure this guard already hit once: before the 160 → 170 raise it sat 21–28 bytes from its ceiling, which is less than a single paragraph, so two independently-compliant PRs could not coexist and correct changes failed on byte count alone.
• 172 KB leaves 2 887 B (~2.8 KB) of real margin — enough that the guard still bites on genuine growth without re-creating a threshold the next change trips by accident. dev's Provision labels correctly in the recommended Squad activation fast path #1959/Use gh-aw temporary IDs for plan activation label targeting #1962 rationale comment is preserved verbatim; Prevent silent truncation of Squad activation label operations #1961's is appended beneath it.

Rebased onto dev

#1965 (fa5cc26c) and #1966 (9e3f6b34) both landed on dev, so this PR is no longer stacked — its base is dev and the diff is #1961-only (3 files).

workflows/squad.md auto-merged with no conflict this round: #1966's edits land in the /squad activate fast path and Step 4, while #1961's are in squad-plan-activate Step 2d/2e. Anchor-grep verified all three contracts survive unduplicated — #1966's Fast-Path Label Provisioning and non-roster reporting, #1965's Temporary-ID Contract and created-count wording, and #1961's capacity budget / max: 110 / Step 2e.

Validation

• 320/320 across 9 targeted suites: gh-aw-activation-capacity, gh-aw-quality, gh-aw-activation-label-provisioning, gh-aw-activation-temporary-ids (fix(workflows): target activation labels via gh-aw temporary IDs #1965's), gh-aw-activate-fast-path-label-provisioning (fix(workflows): provision labels in the /squad activate fast path #1966's, passes untouched), plus the four other suites importing test/helpers/gh-aw-lock.ts.
• Mutation-tested, so the suite is not vacuous: max: 110→80 fails 4 tests including the compiled-runtime assertion; deleting Step 2e's temporary-ID rule fails its test; reintroducing the retracted "never appears as an error" claim fails its negative guard.
• All four workflows compile with gh aw compile --strict; only the pre-existing warnings appear.
• npm run build passes.
• Compiled squad.lock.yml confirms both contracts coexist at runtime: add_labels max 110 (Prevent silent truncation of Squad activation label operations #1961) alongside create_issue max 75 + require_temporary_id: true (fix(workflows): target activation labels via gh-aw temporary IDs #1965).

⚠️ Needs squad member review before merging.

[github-actions]

🟡 Impact Analysis — PR #1964

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-capacity.test.ts
• test/gh-aw-quality.test.ts

---

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

[github-actions]

🛫 PR Readiness Check

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

PR Scope: 🔧 Infrastructure

⚠️ 2 item(s) to address before review

Status	Check	Details
❌	Single commit	9 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	0 active Copilot thread(s) resolved (3 outdated skipped)
✅	CI passing	All checks passing

Files Changed (3 files, +636 −12)

File	+/−
test/gh-aw-activation-capacity.test.ts	+576 −0
test/gh-aw-quality.test.ts	+17 −10
workflows/squad.md	+43 −2

Total: +636 −12

---

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

[Copilot]

Copilot review overview

🟡 Changes recommended

The new test file uses an extensionless ESM helper import (./helpers/gh-aw-lock) that is inconsistent with other suites and can break under Node ESM/NodeNext resolution after transpilation.

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

Review tier: Lite
Findings: 1

New issues introduced by this change (1)

Severity	Finding
	test/​gh-aw-activation-capacity.test.ts — This test imports the helper without the .js extension, but other Vitest suites import the same…

What changed in this PR

This PR hardens the gh-aw activation workflow contract to prevent “green” runs that silently drop add_labels operations under safe-output caps, by increasing the add-labels cap and requiring a reconciliation step that converts any label-operation shortfall into an explicit report_incomplete failure.

Changes:

• Increase safe-outputs.add-labels.max from 80 → 110 and document the capacity rationale (50-issue max, item-vs-label semantics, drop-not-fail behavior).
• Add Step 2e “Label-Operation Reconciliation” guidance to detect and fail on labeled < activated.
• Add a new compiled-artifact contract test suite to lock in capacity math and prove the compiled workflow exposes the required runtime config/tools.

File	Description
workflows/​squad.md	Raises add-labels cap to 110 and documents/mandates reconciliation to prevent silent truncation being reported as success.
test/​gh-aw-activation-capacity.test.ts	Adds capacity + compilation contract tests to validate max sizing, compiled safe-output config, and callable tooling (including report_incomplete).

---

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

[Copilot]

Copilot review overview

🟡 Changes recommended

Step 2e’s report_incomplete reason currently implies labels were actually received/applied during the agent turn, which isn’t guaranteed by an accepted add_labels safe-output and could misreport outcomes.

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

Review tier: Lite
Findings: 1

New issues introduced by this change (1)

Severity	Finding
	workflows/​squad.md — Step 2e’s reconciliation message currently says issues “received their labels”, but at agent time…

Issues resolved since last review (1)

Severity	Finding
	test/​gh-aw-activation-capacity.test.ts — This test imports the helper without the .js extension, but other Vitest suites import the same… View resolved comment

[bradygaster]

Resolved the merge with dev after #1967 (#1963) landed as fb58f26d. Merge commit 4ed083db.

Only one conflict, as expected: SOURCE_GROWTH_BUDGET_KB in test/gh-aw-quality.test.ts. workflows/squad.md auto-merged cleanly — the Step 2d overlap that looked risky resolved without intervention.

The budget is measured, not projected. I merged both branches in a scratch worktree and forced the guard to print its own number rather than trusting an estimate:

Combined authored source is 175.8 KB  (180 036 bytes)
  176 KB -> PASS, headroom    188 B
  177 KB -> PASS, headroom  1 212 B

Set to 177. 176 would pass by 188 bytes, which is precisely the near-zero-margin failure mode this guard's own comment criticises — before the 160→170 raise it sat 21–28 bytes from the ceiling and correct changes failed on byte count alone. #1963's comment predicted this merge would land at ~180 002 B; the real figure is 180 036 B, within 34 bytes, and I've recorded both numbers in the resolved comment so the next raise has a real audit trail.

The guard's stated precondition for a legitimate raise holds: keeps the ambient prompt under 40 KB passes at ~32 KB on the merged tree.

Verification: 286 passed across the six affected suites (gh-aw-quality, gh-aw-activation-capacity, gh-aw-activation-summary-outcomes, gh-aw-activate-fast-path-label-provisioning, gh-aw-agent-binding-correspondence, check-agent-binding).

⚠️ One thing I could not verify locally, reported rather than papered over. gh aw compile --strict fails in this checkout, but it is not this branch: I reproduced it on clean dev at fb58f26d with zero modified files, where it resolves imports from /tmp/sqwt/.github/workflows/ — the parent of the worktree. gh aw compile mis-resolves the repo root inside a linked git worktree. CI runs on a normal clone, so the required gh-aw strict compile check is the authority here, not my local run.

Copilot re-review requested on this head. Not merged.

[Copilot]

Copilot review overview

🟡 Changes recommended

A new test assertion uses a regex alternation that makes the check effectively non-assertive, so the suite may pass even if the intended invariant is removed.

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

Review tier: Lite
Findings: 1

New issues introduced by this change (1)

Severity	Finding
	test/​gh-aw-activation-capacity.test.ts — The regex here is effectively vacuous because the |activated.*artifact alternative will match any…

Issues resolved since last review (1)

Severity	Finding
	workflows/​squad.md — Step 2e’s reconciliation message currently says issues “received their labels”, but at agent time… View resolved comment

[Copilot]

Copilot review overview

🟢 Approval recommended

The changes are narrowly scoped to capacity/rationale + reconciliation safeguards and are backed by compiled-runtime contract tests, with only minor documentation nits noted.

Review tier: Lite
Findings: None

Issues resolved since last review (1)

Severity	Finding
	test/​gh-aw-activation-capacity.test.ts — The regex here is effectively vacuous because the |activated.*artifact alternative will match any… View resolved comment

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

test/gh-aw-quality.test.ts:908

• The source-growth guard below counts the entire workflow file (squadContent includes frontmatter), so the comment claiming all #1961 growth is inside the squad-plan-activate inline skill is inaccurate: this PR also changes the safe-outputs frontmatter (e.g., add-labels max and capacity comments). Please reword to reflect that frontmatter changes exist (and are still stripped from the ambient prompt by the assembler) so future readers don't draw the wrong conclusion about what was measured.

  // All of #1961's growth is inside the `squad-plan-activate` inline skill, which the
  // extractor strips from the ambient prompt and loads on demand; ambient re-measured at
  // 32 KB against 40 KB on the merged tree.

workflows/squad.md:1874

• In the capacity table, the column header is "Safe output" and the create-issue row uses the frontmatter key style, but the next row uses the tool name style (add_labels). This inconsistency can be confusing when someone tries to reconcile the table with the safe-outputs: frontmatter (which is add-labels:). Consider using add-labels in the table and reserve add_labels for places where you're explicitly talking about the tool call/runtime type name.

| `create-issue` | 50 — one per epic/task | 75 |
| `add_labels` | 50 — one per created issue | 110 |
| Labels in one call | 2 — `squad` + `squad:{agent}` | not capped |