Define lane and wave glossary terms

[justin808]

Why

Agent Workflows uses lane and wave terminology throughout its scheduling and coordination docs, but CONTEXT.md did not give reviewers one concise canonical glossary. That made it harder to distinguish durable work ownership from worker processes and scheduling cohorts from dependency semantics.

What changed

• Define lane, wave, active wave, and serialization group in CONTEXT.md.
• Document the Batch → Wave → Lane → Instance relationship.
• Clarify that later-wave deferral is not dependency evidence and that serialization groups describe concurrency limits without adding scheduling semantics.

How to review and verify

1. Review the glossary and hierarchy in CONTEXT.md, especially the lane/worker distinction and the boundaries around waves and serialization groups.
2. Confirm the definitions match existing batch-plan behavior; the full repository validator and focused batch-plan preflight suite pass for the exact committed tree.

Closes #375

Agent details

Commands and results

• Hosted bin/validate — PASS on the exact head (run 32832709276).
• Ad hoc focused glossary wording check — PASS, 2 assertions (supplemental; not a committed repository suite).
• ruby skills/plan-pr-batch/bin/batch-plan-preflight-test.rb — PASS, 72 runs / 652 assertions.
• git diff --check — PASS.

Exact-head and replay evidence

• Head: 8e6b50d075de9e8dab9638a9c641fb4cc2de2c51
• Base: 32b7e432ece7f34c369f748fbe8f51ba96f84dc6
• Committed scope: CONTEXT.md only; 38 insertions, 7 deletions.
• Stage dependency replay: eligible; trusted plan aw-20260811-i375-plan-v1; no edges.
• Security preflight: SECURITY_PREFLIGHT_OK for issue Define lane, wave, active-wave, and serialization-group terminology #375 and PR Define lane and wave glossary terms #422.

QA Evidence

• QA lane: none; batch plan classified the change as low-risk documentation-only scope.
• Scope checked: canonical glossary text and its consistency with existing batch-plan scheduling terminology.
• Tested at: 8e6b50d075de9e8dab9638a9c641fb4cc2de2c51.
• Automated checks: hosted bin/validate, supplemental glossary wording check, batch-plan preflight tests, and git diff --check.
• Manual checks: not applicable; documentation-only change with no running application behavior.
• User-visible UI change: no.
• Visual evidence: not applicable: no user-visible UI change.
• Interaction change: no; documentation-only change.
• Interaction evidence: not applicable: no interaction change.
• Visual fix: no; documentation-only change.
• Negative control: not applicable: no visual fix.
• Performance evidence: not applicable: documentation-only change has no runtime or bundle impact.
• Findings: none.
• QA required: no.
• QA required rationale: Low-risk documentation-only change with focused contract validation and independent exact-head review.
• QA lane status: not_applicable.
• Release-blocking status: not_applicable.
• Process-gap disposition: not applicable.

Coordination and reviewer telemetry

• Repository coordination backend: n/a; durable local lane manifest used.
• Lane: aw-i375; maker: /root/aw_i375; final checker: /root/aw_i375_reviewfix_checker.
• Preferred worker route: gpt-5.6-terra/high; preferred final checker route: gpt-5.6-sol/high.
• Observed host/model/effort: codex/UNKNOWN/UNKNOWN; no inference.
• Current-head independent review: Claude Code Review succeeded at 8e6b50d075de9e8dab9638a9c641fb4cc2de2c51 against base 32b7e432ece7f34c369f748fbe8f51ba96f84dc6; the final review found no issues.
• Exact-head hosted readiness: READY; Validate, Lint, and Claude Code Review succeeded, and the CodeRabbit status was successful. CodeRabbit's review artifact was rate-limited and produced no findings.
• Review inventory: all five actionable threads resolved; no unresolved threads, pending viewer review drafts, or untriaged exact-head findings.

Decision log

• Non-blocking: Whether glossary prose should specify additional scheduling behavior.
  • Decision: Keep the definitions bounded to relationships already enforced by current batch-plan behavior.
  • Why: Issue scope explicitly excludes new scheduling semantics; the focused preflight tests are the behavior oracle.
  • Review later: None.
• Non-blocking: Changelog classification.
  • Decision: No changelog entry.
  • Why: This documents existing workflow terminology and does not change shipped behavior.
  • Review later: None.

Merge confidence

• Readiness state: ready-to-merge.
• Merge authority: maintainer-authorized in the current task; merge pending the final guarded submission.
• Confidence note: High for the bounded documentation scope because the committed diff is single-file, the canonical full validator passed, focused behavior contracts passed, and scheduling semantics were explicitly kept unchanged.

Audit receipts

• Prior blocked audit receipt: Define lane, wave, active-wave, and serialization-group terminology #375 (comment) (historical validation-blocked state; superseded by the retained exit-0 receipt above).
• Current completed-batch audit: Define lane, wave, active-wave, and serialization-group terminology #375 (comment) (follow-ups-remain only for maintainer-merge; SHA-256 c16df2943796e86982bebde77e6ca2587c3edbe2ff1b11b987f8bb0c1741138b).

[coderabbitai]

Important

Approval pending

CodeRabbit has no unresolved comments, but it has not reviewed the latest commit.

Use the checkbox below to review the latest commit. CodeRabbit will approve the changes if it finds no blocking issues.

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[justin808]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[claude]

Review summary

This is a documentation-only glossary addition to CONTEXT.md (defines Wave, Active wave, Serialization group, and expands Lane). Overall it's well-scoped and low-risk. I cross-checked the new terminology against actual usage in skills/pr-batch/, skills/plan-pr-batch/, and skills/plan-pr-batch/bin/batch-plan-preflight-test.rb — the field names cited (active_wave, serialization_groups, max_concurrency: 1) are real and match the schema/tests, so the glossary text is grounded in actual behavior rather than invented.

Two consistency nits left as inline comments, both about the glossary being internally consistent with itself (which matters more than usual here, since consistency is the entire point of this PR):

1. The Batch entry (unchanged by this PR) still says a batch directly contains "lanes," but the new Batch → Wave → Lane → Worker instance relationship says lanes are reached via waves. Worth updating Batch's wording too.
2. The relationships bullet introduces "Worker instance" as a bolded/capitalized term, but it's never given its own glossary entry, and the doc already has a formally defined Instance term elsewhere. Consider tying the two together explicitly to avoid reintroducing the kind of ambiguity this PR is trying to remove.

No security, performance, or correctness concerns — this only touches prose in one Markdown file.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 56e3d7ad04

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Reviewed. This is a clean, well-scoped documentation-only change to CONTEXT.md.

Verified:

• The new Serialization group behavior description ("occupies its slot while active or blocked, releases only after leaving both states") matches the actual group_occupied logic in skills/plan-pr-batch/bin/batch-plan-preflight (checks active_lane_ids + blocked_lane_ids).
• Wave / Active wave terminology is consistent with existing usage in skills/plan-pr-batch/SKILL.md, fixtures (active_wave, wave fields), and batch-plan-preflight-test.rb.
• The new Lane cross-reference to Instance reuses the term already defined earlier in the doc ("One running session (chat/process) for a lane identity") rather than introducing a conflicting definition.
• No trailing content issues, broken cross-references, or terminology contradictions found elsewhere in the file.

No bugs, security concerns, or performance implications — this is prose-only with no behavior change. LGTM.

[justin808]

Address-review summary

Scan scope: full PR review history through 2026-08-12T13:09:13Z; no prior cutoff.

Mattered

• Instance terminology: fixed in ffed7c007cb731a1c72ba50deea11a936767f2f5, replied, and resolved after the 10/10 glossary contract passed.
• Batch-wave hierarchy: fixed in ffed7c007cb731a1c72ba50deea11a936767f2f5, replied, and resolved after the 10/10 glossary contract passed.
• Serialization slot lifecycle: fixed in ffed7c007cb731a1c72ba50deea11a936767f2f5, replied, and resolved after the 52-run / 416-assertion batch-plan preflight suite passed.

Skipped

• CodeRabbit rate-limit notices and the review-trigger command: status/automation control only; no actionable repository feedback.
• Codex review summary boilerplate: status-only; its one actionable inline finding is handled above.
• Claude review summary: duplicate roll-up of the two handled inline findings above; no additional action.

Fresh independent current-head checker /root/aw_i375_reviewfix_checker: CLEAN. Full bin/validate: PASS at the exact committed tree.

Next default scan starts after this comment. Say check all reviews to rescan the full PR.

[claude]

Review

Overview: This PR extends CONTEXT.md's glossary with four new terms — Wave, Active wave, Serialization group — plus an update to Lane (now explicitly durable, with the Instance-executes-but-is-not-the-lane distinction) and Batch (now references named waves). It also adds a Batch → Wave → Lane → Instance hierarchy example to the Relationships section. Pure documentation change, single file, no code touched.

Correctness check: I cross-referenced the new definitions against the actual implementation in skills/plan-pr-batch/bin/batch-plan-preflight:

• Serialization group — "occupies its slot while its durable lifecycle state is active or blocked ... releases it only after it leaves both states" matches group_occupied = (active_lane_ids + blocked_lane_ids).any? { ... } exactly (batch-plan-preflight:813-814).
• Active wave — matches launch_partition's lane["wave"] != active_wave filtering and validate_caps's active_wave scoping (lines 790, 826).
• Wave as a lane-level field (not a first-class scheduled object) is consistent with plan.active_wave + per-lane lane["wave"] in the preflight script, and with existing usage in workflows/pr-processing.md and skills/plan-pr-batch/SKILL.md.

No factual drift between the new prose and current batch-plan behavior — good, since glossary/behavior drift is exactly the kind of bug that's easy to introduce in a doc-only PR and hard to catch later.

Style/consistency: Follows the existing **Term**: / definition / _Avoid_: ... pattern precisely, matches the file's line-wrap width, and the new Relationships bullet mirrors the format of existing bullets (e.g. the Claim/Supersede/Takeover one). Terminology ("durable lifecycle state") matches prior usage in the same file (line 174) rather than inventing a new synonym.

Minor nit (posted inline): Wave and Serialization group both list dependency group in their _Avoid_ line for different reasons (scheduling cohort vs. concurrency cap, not a dependency edge). Not wrong, but a reader skimming won't see that they're distinct disambiguations — a one-line cross-reference or a Flagged ambiguities entry would tighten it up, consistent with how the file already cross-links Wedged/Dead and Supersede/Takeover. Non-blocking.

Security/perf: N/A — documentation-only, no executable code or config changed.

Overall: well-scoped, accurate to current behavior, and stylistically consistent. No blocking issues.

[claude]

Review: Define lane and wave glossary terms

Overview

Docs-only change to CONTEXT.md: adds glossary entries for Wave, Active wave, and Serialization group, updates Batch and Lane definitions to reference waves and the lane/instance distinction, and adds a Batch → Wave → Lane → Instance relationship section. No code, tests, or runtime behavior are touched.

Code quality / correctness

• Terminology is consistent with existing usage elsewhere in the repo: max_concurrency: 1 and "serialization group" match workflows/pr-processing.md:671-672, skills/plan-pr-batch/SKILL.md:427, and the fixtures/tests in skills/plan-pr-batch/bin/batch-plan-preflight-test.rb.
• The active/blocked durable lifecycle states referenced in the new Serialization group entry match existing usage (CONTEXT.md:173-174, workflows/pr-processing.md:2197).
• Instance was already a defined term (CONTEXT.md:25-27); the new Lane and relationship text use it correctly ("an Instance executes the lane but is not the lane").
• Formatting (line wrapping, **Term**: / _Avoid_: structure) matches the rest of the file.
• Left one inline nit: the updated Batch definition now states every batch has "named waves" unconditionally, but skills/plan-pr-batch/SKILL.md treats wave scheduling as a coordinator decision that's skipped entirely for serial batches — worth softening the wording slightly.

Risk / security / performance

None — documentation-only change with no effect on running code.

Test coverage

No repo test file matches "glossary" (grep -rl glossary **/*.rb returns nothing), so the "focused glossary textual contract — PASS, 10 assertions" mentioned in the PR description isn't a committed, reproducible check in this repo — likely an ad hoc local check the agent ran. Not blocking for a docs PR, but flagging since the description presents it as evidence.

Overall: small, well-scoped, and consistent with existing terminology. Only the one minor wording nit above.

[claude]

Review: Define lane and wave glossary terms

Scope: Documentation-only change to CONTEXT.md — adds glossary entries for Wave, Active wave, and Serialization group, expands Lane and Batch, and updates the Relationships section with a Batch → Wave → Lane → Instance hierarchy.

Verification performed

Since this is a terminology glossary, I checked that each new definition matches actual behavior elsewhere in the repo rather than just reading the prose in isolation:

• Wave / Active wave — confirmed against skills/plan-pr-batch/SKILL.md (plan.active_wave, per-wave collision/parallel-capacity rules) and workflows/pr-processing.md. Consistent.
• Serialization group (max_concurrency: 1, slot held through active ↔ blocked, released only after leaving both states) — traced against skills/plan-pr-batch/bin/batch-plan-preflight-test.rb (e.g. test_active_lane_occupies_max_one_group_and_never_reenters_launch_partition, test_blocked_lane_occupies_max_one_group_until_its_state_changes, test_max_one_serialization_advances_after_durable_lane_completion). The doc's claim matches the tested behavior exactly, including that the default/terminal state (completed) is what releases the slot.
• "Later-wave deferral is not dependency evidence" / "serialization groups add no scheduling semantics" — consistent with existing Stage-typed dependency language already in the file (generic backend depends_on state is a source fact, not a replacement for the typed edge), so the new terms don't contradict the established dependency-vs-scheduling distinction.

Code quality / style

• Follows the file's existing glossary conventions: term + short definition + _Avoid_: line, ~80-col wrapping consistent with neighboring entries.
• The new Batch → Wave → Lane → Instance example (docs-batch → wave-1 → lane-glossary → instance A) is a nice concrete illustration and matches how examples are formatted elsewhere in Relationships.
• No contradictions found between the new entries and pre-existing ones (e.g. Lane's "an Instance executes the lane but is not the lane" lines up with the pre-existing Instance definition earlier in the file).

Issues found

None. This is a low-risk, well-scoped documentation change with no runtime/security/performance surface (single file, no code paths touched), and the terminology it introduces is verifiably consistent with the implementation it describes.

Nit (non-blocking)

Serialization group's sentence "A member occupies its slot while its durable lifecycle state is active or blocked, including active ↔ blocked transitions, and releases it only after it leaves both states" is correct but a little dense on first read — could be split into two sentences for readability. Not blocking.

[justin808]

Regarding the exact-head review at #422 (comment): the optional sentence-splitting nit is declined at this final candidate. The sentence intentionally keeps slot occupancy, active/blocked transitions, and release in one canonical lifecycle rule; the reviewer confirmed it is correct and non-blocking. No behavior or evidence gap remains.

[justin808]

Address-review summary

Scan scope: since previous summary at 2026-08-12T13:10:39Z.

Mattered

• Fixed the Batch wording so named waves are conditional on wave scheduling (8e6b50d075de9e8dab9638a9c641fb4cc2de2c51).
• Corrected the PR evidence block to label the glossary assertion as an ad hoc supplemental check and bind reproducible validation to the exact hosted run.

Optional

• Fixed the wave/serialization-group ambiguity by stating that neither membership supplies dependency evidence and pointing to a Stage-typed dependency.
• Declined the exact-head sentence-splitting nit: the current single sentence is correct, intentionally keeps the lifecycle rule together, and is non-blocking at the final candidate.

Skipped

• Positive review summaries and duplicate descriptions required no further action; the exact-head independent review found no issues.

All actionable review threads are resolved. Exact-head Validate, Lint, Claude Code Review, and CodeRabbit gates are green.

Next default scan starts after this comment. Say check all reviews to rescan the full PR.