fix(gh-aw): enforce activation agent bindings - #1865
Merged
Conversation
Closes #1801 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
🟡 Impact Analysis — PR #1865Risk tier: 🟡 MEDIUM 📊 Summary
🎯 Risk Factors
📦 Modules Affectedci-workflows (1 file)
root (2 files)
scripts (1 file)
tests (1 file)
This report is generated automatically for every PR. See #733 for details. |
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 4 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 active Copilot thread(s) resolved (3 outdated skipped) |
| ✅ | CI passing | All checks passing |
Files Changed (5 files, +628 −5)
| File | +/− |
|---|---|
.github/workflows/squad-agent-binding-check.yml |
+52 −0 |
scripts/check-agent-binding.mjs |
+234 −0 |
test/check-agent-binding.test.ts |
+315 −0 |
workflows/shared/squad-planning-ontology.md |
+13 −0 |
workflows/squad.md |
+14 −5 |
Total: +628 −5
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
🏗️ Architectural Review
Automated architectural review — informational only. |
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The new workflow should pin/setup the Node version for deterministic execution, and the @copilot label policy enforced by the checker appears inconsistent with the repo’s established squad:copilot routing label.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR strengthens post-activation enforcement by requiring activation artifacts to emit machine-readable task/epic→issue bindings, and introducing a read-only workflow that validates those bindings against actual GitHub labels to fail closed on inconsistent activation evidence.
Changes:
- Extend activation artifacts (
activated/phases-activated) to include a structured, non-emptybindingsarray describing task/epic issue mappings and intended label outcomes. - Add a deterministic checker script plus Vitest coverage to parse activation structured data, load the roster, and validate binding↔label correspondence.
- Add a post-run GitHub Actions workflow that gathers activation comments from the completed run and executes the checker with
issues: read.
File summaries
| File | Description |
|---|---|
| workflows/squad.md | Adds bindings to the safe-output schema and specifies the activation artifact binding contract. |
| workflows/shared/squad-planning-ontology.md | Documents that activation safe-output data must include a mandatory bindings mapping for post-run validation. |
| scripts/check-agent-binding.mjs | New checker that parses activation structured data, derives expected labels/omissions, and validates against live issue labels via the GitHub API. |
| test/check-agent-binding.test.ts | New tests covering parsing, fail-closed behavior, and workflow wiring/permissions expectations. |
| .github/workflows/squad-agent-binding-check.yml | New workflow_run-triggered read-only validation job that collects activation comments and runs the checker. |
Review details
Suppressed comments (1)
workflows/squad.md:113
- The safe-outputs schema defines
bindings, but the top-levelrequired:list does not require it. That means anactivated/phases-activatedartifact could still validate withoutbindings, despite later activation instructions stating bindings are mandatory and the post-run checker failing closed on missing/empty bindings.
required:
- squad_artifact
- schema_version
- origin_issue
- phases
additionalProperties: false
- Files reviewed: 5/5 changed files
- Comments generated: 4
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The new binding-check workflow is configured to trigger on a non-existent workflow name (Squad), so the validation job will not run.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (2)
workflows/squad.md:98
- The
bindings[*].agentsschema allows an empty array, andomission_reasonis unconstrained. Since the checker enforces non-empty agents and only allowsmulti-owner|non-roster|copilot, tightening the safe-output schema here will catch malformed activation evidence earlier (during emission/validation) instead of only post-run.
agents:
type: array
items:
type: string
label:
workflows/squad.md:1433
- The epic binding example uses
"label":"squad:{agent}", but epic bindings don’t carry anagentfield (onlyagents). This can mis-specify the machine-readable output shape and lead to mismatched labels vs what the deterministic checker expects for single-owner epics.
`{"kind":"epic","issue":{created epic issue number},"epic":"{Epic identifier}","agents":["{distinct lowercased task agents}"],"label":"squad:{agent}"}` for a single roster owner, or omit `label` and set `"omission_reason":"multi-owner"` for multiple owners. For a task whose agent is not certified by TG-2, omit `label` and set `"omission_reason":"non-roster"`; for `@copilot`, use `"omission_reason":"copilot"`. Never omit a created issue from `bindings`, never infer an issue number, and never emit an empty array. The deterministic post-activation workflow treats missing, empty, malformed, or unresolved bindings as a failure.
- Files reviewed: 5/5 changed files
- Comments generated: 1
- Review effort level: Lite
added 3 commits
August 24, 2026 16:35
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 38c1464f-cc45-4217-bd43-09655eee99c8
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 38c1464f-cc45-4217-bd43-09655eee99c8
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 38c1464f-cc45-4217-bd43-09655eee99c8
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Tests
gh aw compile workflows/squad.mdreached workflow-reference validation, then hit the pre-existing missing localsquad-implement-workerdependencyWorking as Procedures (Prompt Engineer).
Closes #1801