Clément Fiere
6.2 KiB
6.2 KiB
id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design
| id | title | status | wave | depends_on | plan | requirements | acceptance_criteria | system_design | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 03-update-queue-automation-documentation | Update Queue Automation Documentation | completed | 3 |
|
plan.md |
|
|
|
Task 03: Update Queue Automation Documentation
Summary
Reconcile public queue guides, configuration reference, and WebSocket reference with the delivered session override and compact header controls. Remove stale claims that capacity is always rejected before a compatible automatic fold.
In scope
- Explain global inheritance and permanent per-session override precedence in user-facing queue guidance.
- Describe the compact Auto-run and Auto-merge pills in the expanded queue header without confusing message merging with pull-request Auto-merge.
- Correct capacity automatic-fold behavior wherever public docs describe queue admission, including the staged-attachment exception.
- Add
queue_incarnation_idto task-session fields. Document requiredtask_id,session_id, andsession_incarnation_idon status get and every queue mutation; the gateway/handler authorize that pair and pass the exact triplet unchanged. Document stale non-retargeting errors, operation-bound response/status snapshots, epoch/generation, availability, and effective Auto-merge value/source/revision. Task-only recounts remain internal. - Keep configuration, operations, coordination, and session guidance consistent without copying detailed protocol text between pages.
- After implementation and behavioral checks pass, perform one lifecycle
cutover: activate both replacement requirements; deprecate the two superseded
requirements without changing their IDs or acceptance text; amend
message-queue-management.mdwith the delivered compatible-fold and staged-attachment capacity exceptions; mark the system design current; and update the UI specification indexes.
Out of scope
- New screenshots, diagrams, or a new public page.
- Changes to GitHub or GitLab pull-request automation documentation.
- Production implementation details already owned by Tasks 01 and 02.
Acceptance
- Public docs state that untouched sessions follow later global changes and an explicitly changed session remains independent for that session's lifetime.
- Queue guidance names both compact pills, eligible direct folding at or above capacity, and staged-attachment rejection, with no contradictory claim in affected pages.
- The WebSocket reference documents exact action/field names, pair authorization, required task/session/incarnation payloads for get and every mutation, non-retargeting errors, operation-bound status snapshots, unavailable ordering, task-only scope, incarnation matching, source/revision, and effective-value semantics. Task-session responses expose immutable queue incarnation. The final cutover leaves replacement requirements active, superseded requirements deprecated with forward links, the management capacity text aligned to delivered behavior, and the system design current.
Verification
python3 scripts/lint-spec-files.test.py
python3 scripts/lint-spec-files.py --all
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
git diff --check -- docs
git diff --cached --check -- docs
git ls-files -z --others --exclude-standard -- docs \
| xargs -0 -r -n1 sh -c 'test -z "$(git diff --no-index --check /dev/null "$1" 2>&1)"' sh
Run all commands from the repository root.
Files likely touched
docs/public/coordination.mddocs/public/operations.mddocs/public/sessions-and-review.mddocs/public/configuration.mddocs/specs/ui/requirements/message-queue-automation-controls.mddocs/specs/ui/requirements/message-queue-auto-merge-session-overrides.mddocs/specs/ui/requirements/message-queue-run.mddocs/specs/ui/requirements/message-queue-management.mddocs/specs/ui/requirements/message-queue-auto-merge.mddocs/specs/ui/system-design/message-queue-automation-controls.mddocs/specs/ui/README.mddocs/public/websocket-api.md
Dependencies
- Task 01 defines the final protocol and persistence behavior.
- Task 02 defines the final user-facing labels and responsive composition.
- This task performs the lifecycle cutover only after Tasks 01 and 02 have passed their behavioral verification; drafts must not become active earlier.
Risks
- Existing pages describe both queued-message Auto-merge and pull-request Auto-merge; edits must remain scoped to message queues.
- Repeating the complete precedence contract across every guide would create another set of drift-prone sources instead of linking to the owning guidance.
- Activating replacements without deprecating and forward-linking the old contracts would leave implementers with conflicting authoritative behavior.
Parallelism
sequential
Inputs
REQ-UI-MESSAGE-QUEUE-AUTOMATION-CONTROLS-001REQ-UI-MESSAGE-QUEUE-AUTO-MERGE-OVERRIDE-001docs/specs/ui/system-design/message-queue-automation-controls.mddocs/decisions/2026-09-04-inherit-queue-auto-merge-until-overridden.md- Current public queue sections in the files listed above.
Results
Completed. Activated the replacement requirements and design, deprecated the superseded queue contracts with forward links, recorded the inheritance decision, and updated public configuration, coordination, operations, session, and WebSocket documentation. Specification and public-doc validation pass.