Skip to content

Standardize work-queue naming across runtime, specs, and ADRs - #65208

Merged
pelikhan merged 2 commits into
mainfrom
pelikhan-work-queue-rename
Oct 3, 2026
Merged

pelikhan merged 2 commits into
mainfrom
pelikhan-work-queue-rename

Conversation

@pelikhan

@pelikhan pelikhan commented Oct 3, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

The work-queue feature still used dispatch-coordinator names across its runtime, compiler, artifacts, and specifications. Standardize the feature on work-queue, with work_queue in AW context and MCP identifiers, so its public interface and implementation use consistent terminology.

  • Use aw_context.work_queue for inbound assignments and expose work_queue_read and work_queue_claim_finish.
  • Rename runtime modules, compiler/report types, smoke/integration workflows, and TLA+ sources together; regenerate the smoke workflow lock file.
  • Update ADRs and specification links. Extend TypeSpec and generated JSON schemas to describe existing workflow transactions, assignments, and finish intents, distinguishing them from operator CLI records.
  • Preserve schema-checked nested assignments in normalized activation context and aw_info.context. Accept legacy work_claim for in-flight workers and normalize it to work_queue; malformed or dual assignments fail closed.
  • Retain existing legacy workflow storage and checked writes until explicit migration, rather than creating an independent empty queue. Both branch names or both log filenames together fail closed. Document quiescing writers and old workflows before migration.
  • Keep historical queue artifacts and compiler-owned log patterns readable by logs/audit, without widening the provenance boundary. New artifacts take precedence; invalid new artifacts cannot be hidden by legacy fallback.

This is not a queue protocol redesign. New workflows use the renamed public tools and identifiers. Legacy reads exist only to preserve historical evidence and live ownership; no automatic storage migration or old MCP tool aliases are added.

Validation

Passed:

  • make fmt, make build, make lint, and impacted Go unit tests.
  • make recompile (302 workflows); the initial rename also passed make check-workflow-drift.
  • Focused work-queue CLI/schema tests and go test -tags=integration ./pkg/workflow -run '^TestWorkQueueCompilationPhases$' -count=1.
  • Impacted Vitest suites after review fixes (136 tests) and npm --prefix actions/setup/js run typecheck.
  • Initial TypeSpec 1.16.0 compilation with sealed JSON schemas, renamed TLA+ trace/witness runner, and both safety-negative controls.

Remaining baseline limitations:

  • make agent-report-progress fails on pre-existing custom Go lint findings in logs/reporting (function length, slice indexing, and discarded close errors).
  • make test was run. Its full Go suite fails in unchanged completion case-sensitivity, shellcheck, chi-square, and Copilot installer tests. Isolated reruns reproduce those failures. This macOS/arm64 host has case-insensitive paths, while installer fixtures assume x64; unrelated failures were not changed or suppressed.
  • The exhaustive positive TLC search was stopped after exceeding the original validation budget; traces and negative controls do not establish exhaustive safety verification.

Prior CI was inspected at log level: 13 checks were cancelled, with no product failure in the inspected cancellation logs. CI on the pushed review-fix HEAD is unverified and must be re-triggered by a maintainer before merge.


Generated by 👨‍🍳 PR Sous Chef · pi · gpt54 · 51.4 AIC · ⌖ 8.63 AIC · ⊞ 9.9K · ◷
Comment /souschef to run again

Use aw_context.work_queue for inbound assignments and rename MCP tools, artifacts, compiler and report types, workflow wiring, TLA+ sources, and ADR references. Define the existing versioned workflow transaction and assignment contracts in TypeSpec and regenerate their schemas.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@pelikhan
pelikhan marked this pull request as ready for review October 3, 2026 02:50
Copilot AI balanced review requested due to automatic review settings October 3, 2026 02:50
@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

✅ Design Decision Gate 🏗️ completed the design decision gate check. See the comment below for the result and any generated ADR draft.

🏗️ ADR gate enforced by Design Decision Gate 🏗️

@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

✅ Test Quality Sentinel completed test quality analysis.

Test Quality Sentinel skipped because pre-fetch PR data was unavailable: unable to fetch test file diff

🧪 Test quality analysis by Test Quality Sentinel

@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

✅ Ponytail Reviewer completed successfully!

Warning

Threat Detection Engine Failure — The analysis engine could not complete. This is a tooling failure, not a security finding.

What happened

The threat detection engine failed to produce results.

Review the workflow run logs for details.

Generated by Ponytail Reviewer for #65208

@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer

@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

✅ PR Code Quality Reviewer completed the code quality review.

🔎 Code quality review by PR Code Quality Reviewer

@github-actions

github-actions Bot commented Oct 3, 2026

Copy link
Copy Markdown
Contributor
🏗️ ADR gate: verified against existing ADRs

Result: ADR-backed and aligned. No additional ADR is required for this PR.

Evidence

  • docs/adr/64955-git-backed-work-queue-coordination.md contains the required Context, Decision, Alternatives Considered, and Consequences sections, and explicitly decides to use work-queue for public names/branches/artifact filenames and work_queue for AW context fields and MCP tool prefixes.
  • docs/adr/65163-report-work-queue-operations-in-audit-and-logs.md also contains all four required sections and covers the work_queue reporting surface for gh aw logs and gh aw audit.
  • The PR diff implements those decisions consistently:
    • renames workflow and artifact paths to work-queue in .github/workflows/smoke-work-queue.md, .github/workflows/smoke-work-queue.lock.yml, work-queue.snapshot.json, and work-queue.finish.jsonl
    • renames MCP/public tool names to work_queue_read and work_queue_claim_finish, and moves inbound context to aw_context.work_queue in actions/setup/js/create_prompt.cjs and actions/setup/js/work_queue_mcp_server.cjs
    • updates reporting/runtime code to the same terminology in pkg/cli/logs_work_queue*.go and actions/setup/js/work_queue_summary.cjs
    • updates protocol/spec references to specs/work-queue/* and the versioned transactions.tsp contract in docs/adr/work-queue-protocol-upgrades.md

Divergences

  • None found from the current PR evidence.

Next action

  • Proceed with normal review; no additional ADR follow-up is required for this gate.

🏗️ ADR gate enforced by Design Decision Gate 🏗️ · pi · gpt54 · 26.8 AIC · ⌖ 9.08 AIC · ⊞ 10.6K · ◷
Comment /review to run again

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied Impeccable distill and extract modes (refactor/rename PR). This is a large, mechanical rename of "dispatch coordinator" → "work-queue" across runtime, specs, schemas, and ADRs. The renamed identifiers, file paths, and documentation are consistent almost everywhere.

Non-blocking finding: one leftover local variable name in pkg/cli/logs_run_processor.go (dispatchBackfillApplied) wasn't updated to match the new workQueue convention used by its sibling flags — see inline comment.

No other correctness, security, or terminology issues found in the diff.

🧵 Reviewed using Impeccable skills by Impeccable Skills Reviewer · copilot · sonnet50 · 66.2 AIC · ⌖ 13 AIC · ⊞ 8.1K

Comment thread pkg/cli/logs_run_processor.go Outdated

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

MCP tool results are discarded and valid nested work-queue context is removed during normalization.

Review effort: Balanced
Findings: 1 Medium severity

Open (1)
What changed in this PR

Standardizes the work-queue terminology across runtime, compiler, reporting, schemas, formal specifications, documentation, and workflows.

Changes:

  • Renames dispatch-coordinator identifiers, files, branches, artifacts, and tools.
  • Adds schemas for workflow transactions, assignments, and finish intents.
  • Updates tests, ADRs, TLA+ tooling, and generated workflow output.
File Description
specs/​work-queue/​WorkQueue.tla Renames the TLA+ module.
specs/​work-queue/​WorkQueue.cfg Adds the primary TLC configuration.
specs/​work-queue/​transactions.tsp Defines operator and runtime schemas.
specs/​work-queue/​traces.sh Uses renamed TLA+ files and output paths.
specs/​work-queue/​RecoveryWitness.cfg Adds recovery witness configuration.
specs/​work-queue/​Recovery.cfg Adds recovery verification configuration.
specs/​work-queue/​README.md Documents renamed protocols and artifacts.
specs/​work-queue/​ExternalEffectWitness.cfg Adds external-effect witness configuration.
specs/​work-queue/​CompetingClaimsWitness.cfg Adds competing-claims witness configuration.
specs/​work-queue/​check.sh Runs renamed TLC models.
specs/​work-queue/​BrokenTerminal.cfg Adds terminal-protection negative control.
specs/​work-queue/​BrokenCAS.cfg Adds CAS negative control.
specs/​dispatch-work-coordinator/​transactions.tsp Removes the old TypeSpec source.
pkg/​workqueue/​schema/​WorkTransaction.json Documents the operator record schema.
pkg/​workqueue/​schema/​WorkQueueWorkTransaction.json Adds runtime Work schema.
pkg/​workqueue/​schema/​WorkQueueWorkCancellationTransaction.json Adds runtime cancellation schema.
pkg/​workqueue/​schema/​WorkQueueTransaction.json Adds the runtime transaction union.
pkg/​workqueue/​schema/​WorkQueueFinishIntent.json Adds finish-intent schema.
pkg/​workqueue/​schema/​WorkQueueCompletionTransaction.json Adds Completion schema.
pkg/​workqueue/​schema/​WorkQueueClaimTransaction.json Adds Claim schema.
pkg/​workqueue/​schema/​WorkQueueClaimCancellationTransaction.json Adds claim-cancellation schema.
pkg/​workqueue/​schema/​WorkQueueAssignment.json Adds inbound assignment schema.
pkg/​workqueue/​schema_test.go Tests storage names and schemas.
pkg/​workqueue/​replay.go Renames operator storage defaults.
pkg/​workqueue/​branch.go Renames branch diagnostics and commits.
pkg/​workflow/​work_queue_compilation_integration_test.go Updates compilation integration coverage.
pkg/​workflow/​notify_comment.go Uses the renamed enablement helper.
pkg/​workflow/​notify_comment_work_queue_test.go Updates summary tests.
pkg/​workflow/​notify_comment_conclusion_helpers.go Loads the renamed summary module.
pkg/​workflow/​mcp_renderer.go Dispatches to the work-queue renderer.
pkg/​workflow/​mcp_renderer_types.go Renames the renderer callback.
pkg/​workflow/​mcp_renderer_test.go Updates MCP rendering coverage.
pkg/​workflow/​mcp_renderer_factory.go Wires the renamed renderer.
pkg/​workflow/​mcp_renderer_builtin.go Renames tools, mounts, and entrypoint.
pkg/​workflow/​mcp_manifest.go Publishes renamed MCP tools.
pkg/​workflow/​compiler_yaml_step_lifecycle.go Renames finish-intent collection.
pkg/​workflow/​compiler_yaml_post_agent.go Collects the renamed artifact.
pkg/​workflow/​compiler_safe_outputs_job.go Renames reconciliation and gating.
pkg/​workflow/​compiler_activation_outputs.go Generates the renamed snapshot step.
pkg/​workflow/​compiler_activation_job.go Calls the work-queue snapshot builder.
pkg/​workflow/​compiler_activation_job_test.go Updates activation tests.
pkg/​workflow/​codex_mcp.go Uses the renamed Codex renderer.
pkg/​parser/​schemas/​main_workflow_schema.json Updates tool documentation.
pkg/​constants/​constants.go Renames work-queue paths and mounts.
pkg/​cli/​work_command.go Updates CLI terminology.
pkg/​cli/​logs_work_queue.go Renames report extraction types and logic.
pkg/​cli/​logs_work_queue_test.go Updates report and artifact tests.
pkg/​cli/​logs_work_queue_render.go Renames report rendering functions.
pkg/​cli/​logs_run_processor.go Propagates renamed report fields.
pkg/​cli/​logs_report.go Renames the structured report field.
pkg/​cli/​logs_orchestrator_filters.go Propagates work-queue reports.
pkg/​cli/​logs_models.go Renames report model fields.
pkg/​cli/​logs_format_compact.go Uses work-queue rendering.
pkg/​cli/​logs_download.go Ensures queue diagnostic logs.
pkg/​cli/​logs_download_workflow_test.go Updates workflow-log fixtures.
pkg/​cli/​logs_cached_json.go Restores renamed cached fields.
pkg/​cli/​audit.go Renames audit analysis state.
pkg/​cli/​audit_summary_build.go Propagates audit queue reports.
pkg/​cli/​audit_run_pipeline.go Backfills renamed report fields.
pkg/​cli/​audit_report.go Renames structured audit output.
pkg/​cli/​audit_report_render.go Renders work-queue operations.
pkg/​cli/​audit_render_output.go Merges renamed queue reports.
pkg/​cli/​audit_cache.go Hydrates renamed cached reports.
pkg/​cli/​audit_analysis_fanout.go Extracts work-queue evidence.
docs/​src/​content/​docs/​reference/​frontmatter-full.md Updates tool terminology.
docs/​src/​content/​docs/​reference/​audit.md Updates report documentation.
docs/​adr/​work-queue-protocol-upgrades.md Adds the renamed protocol ADR.
docs/​adr/​dispatch-work-coordinator-protocol-upgrades.md Removes the old protocol ADR.
docs/​adr/​65163-report-work-queue-operations-in-audit-and-logs.md Adds the renamed reporting ADR.
docs/​adr/​65163-report-dispatch-coordinator-operations-in-audit-and-logs.md Removes the old reporting ADR.
docs/​adr/​64955-git-backed-work-queue-coordination.md Updates the architectural terminology.
actions/​setup/​setup.sh Prepares renamed runtime files and directory.
actions/​setup/​js/​write_work_queue_snapshot.test.cjs Updates snapshot tests.
actions/​setup/​js/​write_work_queue_snapshot.cjs Reads the renamed assignment and store.
actions/​setup/​js/​work_queue_summary.test.cjs Updates summary tests.
actions/​setup/​js/​work_queue_summary.cjs Uses renamed runtime modules.
actions/​setup/​js/​work_queue_store.test.cjs Updates Git-store tests.
actions/​setup/​js/​work_queue_store.cjs Renames runtime branch and storage API.
actions/​setup/​js/​work_queue_replay.test.cjs Updates replay tests.
actions/​setup/​js/​work_queue_replay.cjs Renames replay types and diagnostics.
actions/​setup/​js/​work_queue_mcp_server.test.cjs Updates MCP tool tests.
actions/​setup/​js/​work_queue_mcp_server.cjs Exposes renamed MCP tools.
actions/​setup/​js/​work_queue_codemods.cjs Renames upgrade diagnostics.
actions/​setup/​js/​setup_sh_file_lists.test.cjs Verifies renamed setup files.
actions/​setup/​js/​finish_work_queue_claim.test.cjs Updates reconciliation tests.
actions/​setup/​js/​finish_work_queue_claim.cjs Renames trusted reconciliation logic.
actions/​setup/​js/​create_prompt.test.cjs Updates assignment prompt tests.
actions/​setup/​js/​create_prompt.cjs Reads and describes the renamed assignment.
.github/​workflows/​work-queue-integration.yml Renames integration workflow paths and tests.
.github/​workflows/​smoke-work-queue.md Renames the smoke workflow and tools.
.github/​workflows/​smoke-work-queue.lock.yml Regenerates the compiled smoke workflow.

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

Comment thread actions/setup/js/create_prompt.cjs Outdated
@github-actions

github-actions Bot commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

Comment Memory

reviewed_at: 2026-10-03T02:53:56Z
review_event: REQUEST_CHANGES
top_themes:
  - in-flight worker payload compatibility
  - durable queue storage migration risk
  - historical logs/audit compatibility
files_reviewed:
  - .github/workflows/smoke-work-queue.md
  - .github/workflows/work-queue-integration.yml
  - actions/setup/js/create_prompt.cjs
  - actions/setup/js/finish_work_queue_claim.cjs
  - actions/setup/js/work_queue_store.cjs
  - actions/setup/js/work_queue_mcp_server.cjs
  - actions/setup/js/write_work_queue_snapshot.cjs
  - pkg/cli/logs_work_queue.go
  - pkg/workflow/mcp_manifest.go
  - pkg/constants/constants.go
comment_count: 3

Note

This comment is managed by comment memory.

It stores persistent context for this thread in the code block at the top of this comment.
Edit only the text inside the backtick fences; workflow metadata and the footer are regenerated automatically.

Learn more about comment memory

🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt54 · 102 AIC · ⌖ 7.29 AIC · ⊞ 20.2K · ◷
Comment /review to run again

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Request changes

This rename introduces three blocking regressions: pre-rename worker payloads can bypass queue reconciliation, the durable branch/file rename drops existing live queue state without a migration path, and the logs/audit reader loses compatibility with historical dispatch-coordinator artifacts.

Blocking themes
  • aw_context.work_claim is still present on already-dispatched and retried workers; treating it as absent turns them into unassigned runs that skip the ownership re-check.
  • work-queue / work-queue.jsonl replaces the existing durable storage identifiers without any fallback read or migration, so live queues will look empty immediately after deploy.
  • gh aw logs / gh aw audit now parse only the renamed artifact and step-log identifiers, so older runs lose queue evidence during backfill/regeneration.

🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt54 · 102 AIC · ⌖ 7.29 AIC · ⊞ 20.2K
Comment /review to run again

Comment thread pkg/cli/logs_work_queue.go
Comment thread actions/setup/js/work_queue_store.cjs
Comment thread actions/setup/js/write_work_queue_snapshot.cjs Outdated

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Skills-Based Review 🧠

Applied /codebase-design and /grill-with-docs — approving. This is a disciplined, mechanical rename with no actionable issues found.

📋 Review Notes

Verification performed

  • Grepped the full diff and the checked-out tree for any leftover dispatch-coordinator / dispatch_work_coordinator / DispatchCoordinator identifiers in added lines — none found.
  • Confirmed aw_context.work_queue, work_queue_read, and work_queue_claim_finish are consistently named across pkg/workflow, actions/setup/js, and the TypeSpec/JSON-schema definitions.
  • Confirmed constants (WorkQueueSnapshotPath, WorkQueueFinishIntentDir, WorkQueueFinishIntentMount) are renamed and correctly threaded through mcp_renderer_builtin.go and the compilation integration test.
  • Ran go build ./... (clean) and go test ./pkg/workqueue/... ./pkg/cli/... -run 'WorkQueue' (pass).
  • Checked the new ADR prose (64955-git-backed-work-queue-coordination.md, work-queue-protocol-upgrades.md) — it proactively documents the three-way naming distinction between the workflow runtime's work-queue branch/work_queue context field and the operator CLI's gh-aw-work-queue branch/Transaction format, which is exactly the kind of clarification /grill-with-docs looks for when new vocabulary is introduced.
  • Spot-checked pkg/workqueue/schema/*.json and specs/work-queue/transactions.tsp for cross-references — schema $ids, descriptions, and the WorkQueueTransaction union all align with the Go/JS identifiers.

Positive Highlights

  • ✅ Clear separation maintained between the workflow-runtime WorkQueueTransaction format and the operator-CLI Transaction format, explicitly called out in both code comments and ADRs — avoids a subtle naming collision that could otherwise confuse readers.
  • ✅ Renames applied symmetrically to implementation, tests, and specs in the same commit, so there's no split-brain window where code and docs disagree.
  • ✅ New JSON Schemas for WorkQueueAssignment/WorkQueueFinishIntent/etc. give the previously-implicit wire contract a formally validated, navigable home under pkg/workqueue/schema/.

No functional behavior changes were introduced; nothing to request changes on.

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · copilot · sonnet50 · 114.3 AIC · ⌖ 14.4 AIC · ⊞ 10K
Comment /matt to run again

@gh-aw-bot

Copy link
Copy Markdown
Collaborator

@copilot quick PR triage nudge:

Please refresh this branch if GitHub offers it, address the feedback above, and run the pr-finisher skill before the next review pass.

Generated by 👨‍🍳 PR Sous Chef · pi · gpt54 · 51.4 AIC · ⌖ 8.63 AIC · ⊞ 9.9K · ◷
Comment /souschef to run again

Validate and retain nested work_queue assignments, normalize legacy worker contexts, keep checked writes on existing queue storage, and preserve historical logs/audit evidence. Add regression coverage for in-flight workers, storage conflicts, malformed assignments, and legacy artifacts; finish the backfill flag rename.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@pelikhan
pelikhan merged commit fe02b64 into main Oct 3, 2026
81 checks passed
@pelikhan
pelikhan deleted the pelikhan-work-queue-rename branch October 3, 2026 03:22

Copilot AI commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

@copilot quick PR triage nudge:

Please refresh this branch if GitHub offers it, address the feedback above, and run the pr-finisher skill before the next review pass....

The branch is based on the current main SHA, so no branch refresh was needed. Review feedback is addressed in 2cfc588; the nested work_queue context and related legacy/historical handling are covered by tests, and all review threads are resolved. Local fmt, lint, test-unit, test, focused JS tests, typecheck, and recompile passed. CI on this HEAD is still in progress and needs a maintainer re-trigger after it finishes if required.

@github-actions

github-actions Bot commented Oct 5, 2026

Copy link
Copy Markdown
Contributor

🎉 This pull request is included in a new release.

Release: v0.91.0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants