WEPPcloud
UserSummary Docs

← Back to usersum index

RQ Controller State Contract Foundation

Status: Complete (closed 2026-04-10 04:23 UTC) Timezone: UTC (all dates/times in this package documentation use UTC unless explicitly stated otherwise). Pre-scope note: Scaffold authored at 2026-04-10 03:54 UTC for planned 2026-04-10 kickoff (date retained to match roadmap package ID and user-requested package name).

Overview

This package establishes the implementation foundation for the RQ controller state contract before any endpoint build-out begins. It freezes canonical identifiers, descriptor invariants, and rollout assumptions so follow-on packages can implement APIs without drift between docs, OpenAPI, and route-level behavior.

Objectives

  • Freeze the canonical join-key model for operation_id and step_id across discovery, pipeline, readiness, and OpenAPI.
  • Convert draft-level contract requirements into an implementation-ready baseline with explicit MUST/SHOULD boundaries.
  • Produce a dependency-ordered implementation checklist for downstream work packages.
  • Define verification gates that downstream packages must run to preserve contract alignment.

Scope

This package covers contract-level design hardening, roadmap sequencing, and implementation guardrails only.

Included

  • Review and finalize foundation sections in docs/schemas/rq-controller-state-contract.md.
  • Cross-check contract identifier vocabulary against frozen rq-engine route inventory artifacts.
  • Record explicit implementation assumptions and unresolved decisions in work-package docs.
  • Author and maintain ExecPlan for foundation execution and handoff.

Explicitly Out of Scope

  • Implementing new rq-engine routes or payload handlers.
  • Adding production code for /api/configs, /pipeline, /readiness, or other proposed endpoints.
  • Performing full OpenAPI or test-suite implementation updates beyond planning-level references.

Stakeholders

  • Primary: RQ engine maintainers and agent-interface implementers.
  • Reviewers: Contract/schema maintainers for rq-engine and WEPPcloud docs.
  • Informed: Teams building downstream work packages in the controller-state roadmap.

Success Criteria

  • Foundation contract sections are internally consistent and implementation-ready.
  • Canonical identifier and descriptor invariants are explicitly frozen in docs.
  • Downstream package sequence and dependencies are documented with actionable exit criteria.
  • Required verification commands are documented for follow-on package execution.
  • Tracker and ExecPlan are complete enough for stateless agent handoff.

Dependencies

Prerequisites

  • Existing draft contract:
    • docs/schemas/rq-controller-state-contract.md
  • Existing agent API contract baseline:
    • docs/schemas/rq-engine-agent-api-contract.md
  • Existing route freeze artifacts:
    • docs/work-packages/20260208_rq_engine_agent_usability/artifacts/endpoint_inventory_freeze_20260208.md
    • docs/work-packages/20260208_rq_engine_agent_usability/artifacts/route_contract_checklist_20260208.md

Blocks (Direct)

  • 20260410_rq_controller_state_setup_discovery
  • 20260410_rq_controller_state_orchestration_reads
  • 20260410_rq_controller_state_schema_defaults

Downstream Dependents (Transitive)

  • 20260410_rq_controller_state_geospatial_uploads
  • 20260410_rq_controller_state_errors_progress_outputs
  • 20260410_rq_controller_state_auth_concurrency
  • 20260410_rq_controller_state_contract_cutover
  • Depends on: none
  • Related: 20260208_rq_engine_agent_usability
  • Follow-up: 20260410_rq_controller_state_setup_discovery, 20260410_rq_controller_state_orchestration_reads, 20260410_rq_controller_state_schema_defaults
  • Roadmap source of truth: docs/schemas/rq-controller-state-contract.md (ExecPlan Work-Package Roadmap table)

Timeline Estimate

  • Expected duration: 1-2 focused sessions
  • Complexity: Medium
  • Risk level: Medium

Security Impact and Review Gate

  • Security impact triage: high
  • Dedicated security review required: yes
  • Triage rationale: Package changes include security-sensitive auth/scope contract semantics (rq:read/rq:status rollout behavior and create auth descriptor constraints) that guide downstream implementation.
  • Security review artifact: docs/work-packages/20260410_rq_controller_state_foundation/artifacts/2026-04-10_security_review.md

References

  • docs/schemas/rq-controller-state-contract.md - proposed contract and roadmap.
  • docs/schemas/rq-engine-agent-api-contract.md - canonical companion contract.
  • docs/work-packages/README.md - package process and required artifacts.
  • docs/prompt_templates/codex_exec_plans.md - ExecPlan requirements.
  • PROJECT_TRACKER.md - cross-package scheduling and status board.

Deliverables

  • Work-package scaffold and lifecycle docs:
    • docs/work-packages/20260410_rq_controller_state_foundation/package.md
    • docs/work-packages/20260410_rq_controller_state_foundation/tracker.md
    • docs/work-packages/20260410_rq_controller_state_foundation/prompts/completed/rq_controller_state_foundation_execplan.md
    • docs/work-packages/20260410_rq_controller_state_foundation/prompts/completed/rq_controller_state_foundation_execplan_outcome.md
  • Updated contract docs closing confirmed foundation ambiguities:
    • docs/schemas/rq-controller-state-contract.md
    • docs/schemas/rq-engine-agent-api-contract.md
  • Security review artifact:
    • docs/work-packages/20260410_rq_controller_state_foundation/artifacts/2026-04-10_security_review.md
  • Updated PROJECT_TRACKER.md lifecycle entry for this package.
  • Independent reviewer subagent findings with disposition captured in tracker notes.

Closure Notes

  • Reconciled identifier model language with frozen artifacts by freezing operation_id alignment semantics and path-exception handling.
  • Clarified descriptor invariants by defining catalog vs schema/default descriptor shapes and checklist parity boundaries.
  • Clarified roadmap dependency notation and direct vs transitive package dependencies for handoff.
  • Completed required validation gate:
    • wctl doc-lint --path docs/schemas/rq-controller-state-contract.md --path docs/schemas/rq-engine-agent-api-contract.md --path docs/work-packages/20260410_rq_controller_state_foundation/package.md --path docs/work-packages/20260410_rq_controller_state_foundation/tracker.md --path docs/work-packages/20260410_rq_controller_state_foundation/prompts/completed/rq_controller_state_foundation_execplan.md --path docs/work-packages/20260410_rq_controller_state_foundation/prompts/completed/rq_controller_state_foundation_execplan_outcome.md --path docs/work-packages/20260410_rq_controller_state_foundation/artifacts/2026-04-10_security_review.md --path PROJECT_TRACKER.md (8 files validated, 0 errors, 0 warnings).
  • Root PROJECT_TRACKER.md entry moved from Backlog to Done.

Follow-up Work

  • Start 20260410_rq_controller_state_setup_discovery once this package is marked closed.
  • Start orchestration read endpoints package after setup discovery alignment.
  • Revisit contract freeze after first implementation package to capture discovered deltas.