Repository navigation
Add scoped GitHub Issues mirrors for the Git-backed work queue - #67025
Conversation
Keep Git authoritative while projecting checked admissions and original Claims through protected activation and conclusion hooks. Add immutable bindings, scoped native-field and comment projection, conservative recovery, checked GraphQL transport, packaged message templates, and required token permissions. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
✅ Ponytail Reviewer completed successfully!
|
|
✅ Test Quality Sentinel completed test quality analysis. Test Quality Sentinel skipped because pre-fetch PR data was unavailable: unable to fetch test file diff
|
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. See the comment below for the result and any generated ADR draft.
|
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅
|
|
✅ PR Code Quality Reviewer completed the code quality review.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Ponytail review: one dead guard can be removed.
net: -1 lines possible.
Generated by ✂️ Ponytail Reviewer for #67025 · codex · gpt56 · 22.8 AIC · ⌖ 6.33 AIC · ⊞ 13.4K
Comment /ponytail to run again
🏗️ Design Decision Gate — ADR RequiredThis PR makes significant changes to core business logic (~1500 new lines across 📄 Draft ADR committed:
📋 What to do next
Once an ADR is linked in the PR body, this gate will re-run and verify the implementation matches the decision. 🔍 Evidence used
❓ Why ADRs Matter
ADRs create a searchable, permanent record of why the codebase looks the way it does. Future contributors (and your future self) will thank you. 📋 Michael Nygard ADR Format ReferenceAn ADR must contain these four sections to be considered complete:
All ADRs are stored in
|
There was a problem hiding this comment.
REQUEST_CHANGES
The queue→Issue projector still has a blocking recovery hole: both Issue creation and comment creation can get stuck permanently after a local interruption because the journal is written before the native mutation is attempted. It also regresses rerun status from Running back to Assigned.
🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt54 · 65.1 AIC · ⌖ 5.54 AIC · ⊞ 19.9K
Comment /review to run again
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /codebase-design (architecture/seam review, per pr-triage fallback — /tdd coverage was already extensive and didn't surface actionable gaps) across the new Issue-mirroring subsystem (work_queue_issues.cjs, work_queue_issue_api.cjs, work_queue_issue_contract.cjs). No blocking correctness issues found; comments below are about interface clarity and reducing duplicated magic numbers/logic as this subsystem grows.
📋 Key Themes & Highlights
Key Themes
- Deep-module boundary blur in
main()(work_queue_issues.cjs): rate-limit pacing/instrumentation is inlined into the top-level orchestration function, making it harder to unit test in isolation. - Repeated magic numbers: the
25-target batch cap appears in 4+ places across two files with no single source of truth. - Dense invariant encodings:
isRejectedIssueCreationand the comment-handle collision check inapplyIssueBindingcorrectly implement subtle, load-bearing rules, but their current one-liner form makes the "why" hard to recover without re-deriving the invariant.
Positive Highlights
- ✅ Comprehensive compatibility story: closed-schema versioning, explicit pending states instead of silent fallback, no blind retries of ambiguous native writes.
- ✅ Strong test coverage for the trickiest concurrency/ambiguity paths (batch chunking at 50, rate-limited retry vs. ambiguous-timeout, partial malformed creation responses).
- ✅ Documentation (
docs/reference/work-queue.md) clearly explains the newissuesconfig, authority model, and recovery semantics — no/grill-with-docsgaps found.
Note: the pre-fetched diff patch is capped at 3000 lines and was truncated partway through docs/src/content/docs/reference/frontmatter-full.md; the Go-side files (pkg/workflow/work_queue_issues.go, pkg/workqueue/issues.go, schema JSON) were not visible in the diff and were only spot-checked directly in the working tree, not reviewed in full.
@copilot please address the review comments above.
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · copilot · sonnet50 · 114.1 AIC · ⌖ 13.8 AIC · ⊞ 10.1K
Comment /matt to run again
There was a problem hiding this comment.
🟡 Changes recommended
Worker conclusion projection currently cannot authenticate, and projector policy validation is inconsistent across readers.
3 open findings
What changed in this PR
Adds GitHub Issues as an optional human-facing mirror for the Git-backed work queue while preserving Git as the authority.
Changes:
- Extends queue contracts with projector rules, Issue links, and comment handles.
- Adds activation/conclusion projection with scoped credentials and checked publication.
- Adds templates, documentation, and extensive Go/JavaScript coverage.
Security review found no agent credential exposure, but identified worker conclusion authentication and cross-reader contract inconsistencies.
| File | Description |
|---|---|
specs/work-queue/transactions.tsp |
Extends the queue contract. |
specs/work-queue/README.md |
Documents contract compatibility. |
pkg/workqueue/types.go |
Adds Go projector and Issue state types. |
pkg/workqueue/schema/WorkOperation.json |
Adds backing-Issue schema. |
pkg/workqueue/schema/SubmitParameters.json |
Supports backing Issues on submission. |
pkg/workqueue/schema/RequestParameters.json |
Adds projector operations and policy. |
pkg/workqueue/schema/QueueRequest.json |
Adds Issue-link requests. |
pkg/workqueue/schema/QueuePolicy.json |
Adds projector rules. |
pkg/workqueue/schema/QueueOperation.json |
Adds Issue operations. |
pkg/workqueue/schema/QueueCommit.json |
Extends commit records. |
pkg/workqueue/schema/ProjectorRule.json |
Defines projector authority. |
pkg/workqueue/schema/PolicyOperation.json |
Extends policy operations. |
pkg/workqueue/schema/OperationsParameters.json |
Adds Issue operation parameters. |
pkg/workqueue/schema/IssueLinkOperation.json |
Defines immutable Issue links. |
pkg/workqueue/schema/IssueCommentOperation.json |
Defines comment handles. |
pkg/workqueue/schema/DispatchOperation.json |
Allows projector actors. |
pkg/workqueue/schema/Actor.json |
Adds the projector role. |
pkg/workqueue/request.go |
Authorizes projector requests. |
pkg/workqueue/replay.go |
Replays Issue bindings. |
pkg/workqueue/policy.go |
Validates projector permissions. |
pkg/workqueue/issues.go |
Implements Go projection authority. |
pkg/workqueue/issues_test.go |
Tests Go/JavaScript parity. |
pkg/workqueue/graph.go |
Validates backing-Issue uniqueness. |
pkg/workqueue/evidence.go |
Verifies backing-Issue identity. |
pkg/workflow/work_queue_policy.go |
Integrates Issue configuration. |
pkg/workflow/work_queue_issues.go |
Generates projection steps and tokens. |
pkg/workflow/work_queue_issues_test.go |
Tests workflow compilation. |
pkg/workflow/notify_comment.go |
Adds conclusion projection. |
pkg/workflow/notify_comment_conclusion_helpers.go |
Ensures conclusion execution. |
pkg/workflow/compiler_activation_permissions.go |
Grants activation permissions. |
pkg/workflow/compiler_activation_outputs.go |
Adds activation projection. |
pkg/parser/schemas/main_workflow_schema.json |
Defines frontmatter configuration. |
docs/src/content/docs/specs/work-queue-specification.md |
Records implementation evidence. |
docs/src/content/docs/reference/work-queue.md |
Documents backing Issues. |
docs/src/content/docs/reference/frontmatter-full.md |
Documents new frontmatter fields. |
docs/src/content/docs/guides/deploy-work-queue.md |
Adds deployment guidance. |
actions/setup/md/work_queue_issue_summary.md |
Adds summary template. |
actions/setup/md/work_queue_issue_status.md |
Adds status template. |
actions/setup/md/work_queue_issue_claim.md |
Adds Claim template. |
actions/setup/md/work_queue_issue_body.md |
Adds Issue body template. |
actions/setup/md/work_queue_generated_footer.md |
Adds attribution template. |
actions/setup/js/write_work_queue_snapshot.cjs |
Projects during activation. |
actions/setup/js/work_queue_store.cjs |
Enables checked GraphQL transport. |
actions/setup/js/work_queue_replay.cjs |
Replays Issue records. |
actions/setup/js/work_queue_policy.cjs |
Validates projector policies. |
actions/setup/js/work_queue_mcp_server.cjs |
Accepts backing-Issue submissions. |
actions/setup/js/work_queue_issues.test.cjs |
Registers projector tests. |
actions/setup/js/work_queue_issues.cjs |
Implements Issue projection. |
actions/setup/js/work_queue_issues_checks.cjs |
Tests projector behavior. |
actions/setup/js/work_queue_issues_acceptance.test.cjs |
Registers acceptance tests. |
actions/setup/js/work_queue_issues_acceptance_checks.cjs |
Tests recovery and transport. |
actions/setup/js/work_queue_issue_messages.cjs |
Renders Issue content. |
actions/setup/js/work_queue_issue_journal.cjs |
Validates durable receipts. |
actions/setup/js/work_queue_issue_coordination.cjs |
Coordinates concurrent projection. |
actions/setup/js/work_queue_issue_contract.cjs |
Enforces Issue authority. |
actions/setup/js/work_queue_issue_api.cjs |
Implements native Issue operations. |
actions/setup/js/work_queue_intents.cjs |
Normalizes backing Issues. |
actions/setup/js/work_queue_graph.cjs |
Validates Issue-backed Work. |
actions/setup/js/work_queue_documentation.test.cjs |
Tests deployment examples. |
actions/setup/js/work_queue_dispatch.cjs |
Resolves backing-Issue identity. |
actions/setup/js/work_queue_checked_transport.cjs |
Adds checked GraphQL reads/writes. |
.github/aw/work-queue.md |
Adds concise operator guidance. |
🧠 Review effort: Balanced
Authenticate worker conclusion projection with original dispatch provenance. Preserve conservative ambiguous-write recovery with regression coverage, verify oversized mutation chunking, and finalize the architecture decision record. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Require exact installed grants for existing Issues and trusted admission-time closure policy. Preserve native reader parity, clarify recovery and request pacing, and integrate main with regenerated schema documentation. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copy the Issue contract and checked transport into the isolated safe-outputs runtime. Add explicit deployment coverage while retaining the transitive dependency assertion that caught the missing files in JavaScript shard 4. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
@copilot conduct a security review, DevOps review, and GitHub API usage review. Update the compiler thread specification. |
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Security review found no exploitable issue. The DevOps review confirmed that rejecting |
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
|
@copilot address the following outstanding work in one pass:
Push the necessary fixes, reply to each listed review thread and resolve it when addressed. Ignore feedback already answered or resolved. Use the pr-finisher skill and stop when only human review or CI remains; do not trigger CI. Sous-chef head: 645a8e1
|
…ssues # Conflicts: # actions/setup/js/work_queue_store_checks.cjs Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
Merged current |
|
@copilot update TLA+ specs and model. |
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Added |
|
🎉 This pull request is included in a new release. Release: |
Why
Git-backed queue state is durable and authoritative, but difficult for humans to follow during execution and delivery. This adds GitHub Issues as a human-facing mirror of already-admitted Work without changing scheduling, Claim authority, or Result verification.
Approach
tools.work-queue.issuesconfiguration with a defaultworklabel and optional pre-provisioned native organization single-select status field. No Project, Issue intake, global reconciliation, new job, or new trigger is introduced.backing_issue, checkedIssueLinkandIssueCommentrecords, and installed projector rules. Scope every mutation to this run's checked admissions or original authenticated Claims, including workflow revision, principal, run, and attempt.projectors[].backing_issuesgrants for pre-existing Issues at admission and independently for the actual projecting principal/workflow/revision. Projector-created mirrors use verified creation receipts and checked links. Repository access, agent payload, markers, and summary handles do not establish target ownership.projectors[].completion_policyfrom Policy at Work admission; default keep-open and later policy expansion cannot grant closure retroactively.actions/setup/md, always including generated-by attribution. UsewithRetryfor proven pre-execution creation rejections, never blind retries of ambiguous writes. Protected hook and App tokens requestcontents: write,issues: write, andactions: read; agents do not receive writer credentials.Architecture decision: ADR-67025: Scoped GitHub Issues mirrors.
Compatibility and recovery
Upgrade every closed-schema version-3 reader and deployment before enabling the new records. Administrators provision native fields/options separately. Missing or unwritable fields leave the queue committed and synchronization explicitly pending. Unprovable native writes retain non-expiring coordination rather than risk duplicate creation or stale updates; only authorized hooks for the same Work/Claims may retry.
An interruption before sending and an accepted native write followed by loss of its receipt can leave identical durable state. Those targets can remain pending indefinitely; automatic safe fence recovery is not implemented, and merely running a later authorized hook cannot establish the missing creation provenance. No exactly-once recovery-liveness guarantee is claimed.
Mocked authenticated hook budgets cover coordination and receipt publication: 6 requests for 25 unchanged Issues, 9 for an existing Issue/new summary, and 15 for new Issue creation, bindings, and coordination. Ordinary checked queue read/publication takes 2 requests. Shared activation work and App token minting are additional; live mutation primary cost is not claimed.
Validation
npm run typecheckandnpx vitest run work_queue --no-file-parallelism: 954 tests pass across 48 suites.471bb38b15, as did shard 3/4.SAFE_OUTPUTS_FILESomitted two PR-added transitive dependencies.f4e254f5e9bac7547f4226f91ae283f26ac78752addswork_queue_issue_contract.cjsandwork_queue_checked_transport.cjsto the isolated runtime, retaining the original assertion and adding explicit coverage. All 15 deployment tests pass. The exact shard passes locally: 136 suites passed, 2 skipped; 4,231 tests passed, 26 skipped, using Bash 5 and canonical session-local runner/workspace paths.python3 specs/work-queue/generate_contract.py --check, pinned official TypeSpec 1.16.0 compilation/emission, andverify_official_contract.py: all 45 schemas match.make build,make build-wasm, formatting, lint, and the finalmake agent-report-progresspass. All 333 existing workflows compile without lock drift. The packaging follow-up also passes typecheck, JavaScript lint, and its own final publication gate.Coverage includes concurrent binding collisions, overlapping projectors, partial/malformed receipts, shared queues, original-worker native authentication and rerun refusal, indistinguishable interrupted Issue/comment creation, oversized mutation chunking, comment-only status changes, native-field no-ops, missing permissions, label repair, staged behavior, exact target grants, admission-time closure policy, packaged runtime dependency completeness, and mandatory footer rendering. No live Issue/organization-field writes or hosted workflow runs were performed.
Finisher and CI hand-off
The authority/review fixes are pushed as
471bb38b15d38261902d4e934050768f3529504a; all eight additional review threads were replied to and resolved. The deployment follow-up is pushed asf4e254f5e9bac7547f4226f91ae283f26ac78752; a final review read still finds zero unresolved threads. Current main was integrated without conflicts in the earlier pass, and regenerated documentation fixes the missingwork-queue: trueexample reproduced from CI's synthetic merge without weakening the assertion.CI did run on
471bb38b15; a re-trigger was not the blocker for that HEAD. Itslint-go-govulncheckfailure still reports 11 inherited Go 1.26.8 standard-library vulnerabilities, fixed in Go 1.26.9. Dependency manifests and traced existing sources were unchanged by this feature; this remains an external toolchain blocker, not a suppressed check. Shard 4's PR-introduced packaging defect is fixed and locally reproduced green in the follow-up.CI for the new
f4e254f5e9HEAD is unverified in this hand-off; no workflows were manually triggered, re-run, or watched. The PR is mergeable and non-draft, but human approval and successful CI are still required. It has not been merged.