fix(workflow): forward-port safe-output reliability hardening from #1683

[bradygaster]

Summary

Forward-port of the intended reliability changes from #1683 onto the current compressed origin/dev (which includes merged #1685 / commit 39077ce2).

Why Manual Forward-Port Was Required

PR #1683's branch (squad/safe-outputs-reliability-hardening) still contains the pre-compression 112 KB workflows/squad.md. Rebasing or merging that branch would restore the uncompressed file and violate the 100 KB gh-aw ceiling. This PR applies only the coherent reliability changes onto the already-compressed prompt (33 KB).

Changes (workflows/squad.md)

Fix	Impact
create-issue max: 50 → 75	Supports larger plans without hitting output cap silently
Output Budget Awareness	Phasing guidance when >50 issues; compact bodies when >30
Label Pre-flight	Validates squad/squad:{agent} labels exist before first create-issue
Transient Failure Handling	Single retry on 5xx; skip+report on second failure or 4xx
Sub-issue Fallback	Graceful degradation on 404/422 — records parent as body reference

Architecture Notes

• Changes are terse inline guidance within Plan Activate — no new phases, no structural redesign
• Compressed prompt architecture preserved; token-optimization principles followed
• Label pre-flight uses the existing issues: read permission — gh-aw safe-outputs platform layer handles the write; no scope change needed
• No speculative redesign; all five behaviors are deterministic guidance within existing Plan Activate steps

Prompt Budget

	Before	After
workflows/squad.md	32,196 bytes (32 KB)	33,388 bytes (33 KB)
Headroom to 100 KB ceiling	~69 KB	~67 KB

Validation

• ✅ gh-aw-quality.test.ts — 34 tests pass (7 new: max=75 assertion, 4 hardening behaviors, headroom guard, combined bytes report)
• ✅ npm run build passes
• ✅ git diff --check — no whitespace errors in staged files
• ✅ No lock artifacts committed; no unintended deletions
• ⏳ gh aw compile squad --strict --approve — requires gh-aw extension; not available in this environment

Supersedes

This PR supersedes #1683. Do not merge #1683 — it carries the pre-compression file that would break the 100 KB limit.

Refs #1678

[github-actions]

🟡 Impact Analysis — PR #1686

Risk tier: 🟡 MEDIUM

📊 Summary

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

🎯 Risk Factors

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

📦 Modules Affected

root (1 file)

• workflows/squad.md

tests (1 file)

• 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 0d136af

PR Scope: 🔧 Infrastructure

⚠️ 3 item(s) to address before review

Status	Check	Details
❌	Single commit	2 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	2 unresolved Copilot thread(s) — fix and resolve before merging
✅	CI passing	All checks passing

Files Changed (2 files, +82 −1)

File	+/−
test/gh-aw-quality.test.ts	+65 −0
workflows/squad.md	+17 −1

Total: +82 −1

---

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

[bradygaster]

FIDO Quality Review — PR #1686

Verdict: REQUEST_CHANGES (same-user restriction prevents formal review — evidence comment in lieu)

---

❌ BLOCKING — Label Pre-flight: Success-Shaped Impossible Guidance

File: workflows/squad.md line 720

The instruction reads:

"If missing, create them with color 0075ca / e4e669 and description. Safe-output permissions handle the write — no additional token scope needed."

This is factually wrong on two counts:

1. Permission mismatch: The workflow declares issues: read (line 23). Label creation requires issues: write. The read scope will receive a 403.

2. No create-label safe-output configured: The safe-outputs block has only create-issue, add-comment, create-pull-request. The gh-aw platform cannot write labels without a create-label safe-output entry. The PR description compounds this: "Label pre-flight uses the existing issues: read permission" — read cannot create labels.

The "Skip silently if label creation fails" fallback prevents a hard crash, but the instruction still claims a capability the runtime provably lacks. This is the "success-shaped impossible guidance" pattern the review brief specifically targets.

Minimum fix: Remove the creation clause. Replace line 720 with:

Before the first create-issue, verify labels squad and any squad:{agent} exist. If missing, record them in the activation summary as a prerequisite gap (requires issues: write + create-label safe-output — not configured). Continue activation — create-issue will apply existing labels normally.

---

⚠️ NON-BLOCKING — Changeset Misattributed

File: .changeset/fix-safe-outputs-plan-activate-hardening.md

Targets "squad-cli": patch but the PR touches only workflows/squad.md and test/ — neither is under packages/squad-cli/src/. Per repo policy, changeset is not required for workflow-only changes. This will trigger an unnecessary squad-cli version bump.

Fix: Remove the changeset and add the skip-changelog label.

---

✅ PASSED — Evidence

Check	Result
Base includes 39077ce / PR #1685	✅ git merge-base confirms 39077ce2
No stale pre-compression content from #1683	✅ Diff: +17/-1 workflows/squad.md, +49 tests, +1 changeset only
squad.md byte count	✅ 33,388 bytes (32.6 KB)
Total prompt size (with imports)	✅ 33,388 bytes — no external imports pulled in
Headroom to 100 KB ceiling	✅ 67.4 KB — healthy
Headroom guard (>5 KB threshold)	✅ Passes; 67.4 KB actual vs. 5 KB floor
All 34 tests pass	✅ vitest run test/gh-aw-quality.test.ts — 34/34, 29ms
create-issue max = 75 assertion	✅
Output budget phasing guidance (>50 issues)	✅ Regex match
Transient failure handling (5xx retry)	✅ Regex match
Sub-issue fallback (404/422 degrade gracefully)	✅ Regex match
CI checks	✅ 12 pass, 2 skipping, 1 pending (test — expected)
gh aw compile squad --strict --approve	⏳ Extension unavailable in this environment

---

Summary

Two issues: one blocking (Label Pre-flight claims issues: read can create labels — it cannot, and no create-label safe-output exists), one non-blocking (unnecessary changeset targets wrong package). All other hardening changes — max=75, output budget awareness, transient retry, sub-issue fallback — are internally consistent, well-tested, and correctly scoped. Fix the label guidance and the changeset; this is otherwise mergeable.

— FIDO, Quality Owner

[Copilot]

Pull request overview

Forward-ports safe-output reliability hardening guidance (originally from #1683) onto the compressed workflows/squad.md, and adds regression tests/changeset metadata to keep the workflow prompt reliable under gh-aw constraints.

Changes:

• Increase safe-outputs.create-issue.max from 50 → 75 in workflows/squad.md.
• Add Plan Activate inline guidance for output budgeting, label pre-flight, transient failures, and sub-issue fallback.
• Add test coverage to enforce the new max and assert the new Plan Activate guidance exists; add a changeset entry.

Show a summary per file

File	Description
workflows/squad.md	Raises create-issue cap and adds Plan Activate reliability guidance blocks.
test/gh-aw-quality.test.ts	Adds assertions for max: 75, headroom guard, and presence of hardening guidance text.
.changeset/fix-safe-outputs-plan-activate-hardening.md	Adds a release note entry for the change (but needs the correct package name).

Review details

Tip

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

Suppressed comments (1)

workflows/squad.md:721

• "Label Pre-flight" says to create missing squad / squad:{agent} labels with no additional token scope and to skip silently if label creation fails. In this workflow, permissions.issues is read (and there is no safe-output configured for label creation), so label creation is unlikely to succeed. Skipping silently would then cause subsequent create-issue calls (which apply the squad label by default) to fail with 422 and skip most/all issues. Prefer a deterministic fallback: if required labels are missing and cannot be created, stop early with a clear instruction to run squad init/upgrade or create the labels in the repo before activating.

##### Label Pre-flight

Before the first `create-issue`, check that labels `squad` and any `squad:{agent}` exist. If missing, create them with color `0075ca` / `e4e669` and description. Safe-output permissions handle the write — no additional token scope needed. Skip silently if label creation fails; continue activation.

• Files reviewed: 3/3 changed files
• Comments generated: 3
• Review effort level: Lite

[bradygaster]

FIDO — Quality Owner Review ✅ APPROVE (evidence comment — same-user restriction prevents formal review submission)

Reviewed at EECOM revision SHA 0d136af

Blocking Finding — Fully Resolved

The label-creation impossibility is closed. EECOM commit 0d136af replaced the impossible creation claim ('safe-output permissions handle the write') with truthful preflight: verify existence, record missing labels as a prerequisite gap in the activation summary (notes that issues: write and a create-label safe-output would be needed but are not configured), continue activation normally, omit unavailable labels and report them. No cascade 422 risk. ✅

All Four Hardening Behaviors Preserved

• create-issue max raised to 75 — locked by test asserting exact toBe(75) ✅
• Output Budget Awareness block present at lines 714–716 — regex verified ✅
• Transient Failure Handling block present at lines 722–724 — regex verified ✅
• Sub-issue Fallback block present at lines 726–728 — regex verified ✅

Prompt Budget

Runtime total at 0d136af: 59,329 B (57.9 KB) against 100 KB gh-aw ceiling. Headroom: 42.1 KB. Headroom guard test passes (>5 KB threshold). ✅

Breakdown: squad.md 33,500 B + shared/squad.md 6,688 B + planning-ontology.md 15,231 B + planning-policy.md 3,910 B. Planning imports correctly preserved per #1685.

Changeset Removal — Correct

Net diff vs origin/dev: exactly 2 files (test/gh-aw-quality.test.ts +65, workflows/squad.md +17/-1). No changeset in net diff. Changeset Drift CI: PASS. Workflow+test-only change; no SDK/CLI source touched; no package changeset required. ✅

Test Execution Evidence

Run against PR branch files checked out locally:

npx vitest run test/gh-aw-quality.test.ts
✓ test/gh-aw-quality.test.ts (37 tests) 103ms
Tests: 37 passed

24 original + 1 max=75 lock + 1 headroom guard + 2 planning import regression guards + 9 hardening behavior tests = 37 total. All 17 new regex patterns independently verified against actual squad.md content.

CI Status

16/16 completed checks: PASS (Scope Boundary and docs-quality: skipped — expected). test job was in_progress at review time (normal ~5 min full suite). Local execution covers this job's scope directly.

No New Defects

Permissions unchanged (issues: read is correct — safe-output platform handles writes). No new safe-output types, no imports changed, no structural changes. Label pre-flight is read-only + summary output only. #1683 correctly superseded with explicit do-not-merge warning in PR body.

FIDO verdict: GO. Quality gate cleared. Ready to merge pending test job completion.