schema_version: qa-test-requirements-v1
status: active
enforcement: Enforced
source: Runtime QA Test Requirement Resolver

default_category: docs_only

evidence_keys:
  - summary_validation
  - governance_validation
  - research_checkpoint
  - state_model
  - deterministic_transition_tests
  - forbidden_transition_tests
  - adversarial_sequence_tests
  - backend_e2e
  - frontend_component_or_service_tests
  - browser_proof
  - architecture_drift_check
  - full_validation
  - work_registration_visibility
  - final_clean_pass

mechanism_policy:
  checkpoint_section: Research/Design Checkpoint
  fast_learn_fast_fail: >-
    Do not narrow a critical-path gap when following chunks depend on it.
    Research/inspect, then close it now if a clear feasible success path exists
    and the fix is localized. Stop only when research cannot determine a clear
    path forward, no plausible solution exists, success criteria remain
    ambiguous, authority policy conflicts, unsafe global settings are required,
    product semantics are unclear, or a dependency cannot be verified locally.
  localized_redesign_allowed: true
  stop_only_when_no_clear_feasible_success_path: true
  docs:
    - ai/standards/research-gated-mechanisms.md

proof_policy:
  baseline_strategy: diagnose_cases_then_integrated_clean_pass
  root_cause_required: true
  description: >-
    QA may use a greedy diagnostic loop while implementing or repairing a
    stateful/live behavior: run the next failing case, fix it, and continue to
    the next case. QA PASS for the chunk still requires one uninterrupted final
    clean run across the required sequence after all individual failures are
    handled.
  root_cause_policy: >-
    Root-cause analysis is required for failures and regressions. Symptom
    patches, fallback polling, retries, or resilience layers are acceptable only
    after the root cause has been identified, improved where feasible, and the
    fallback has bounded side effects with explicit proof.
  applies_to_categories:
    - frontend_state_machine
    - backend_state_machine
    - socket_live_update
    - browser_visible_behavior
    - service_recovery
    - work_registration
    - validation_runner
  final_clean_pass_required: true
  fallback_strategy: >-
    If the greedy diagnostic loop shows that cases are highly dependent and
    fixing one case destabilizes earlier cases, return to serialized proof:
    prove each case in dependency order, then rerun the full sequence once.
  research_backed_alternative_allowed: true
  alternative_requirement: >-
    A more efficient QA strategy may replace this baseline only after a
    research/design checkpoint shows it provides equivalent coverage and still
    produces an integrated final proof artifact.

mechanisms:
  connection_reconnect:
    categories: [frontend_state_machine, socket_live_update]
  state_machine:
    categories: [frontend_state_machine, backend_state_machine]
  service_recovery:
    categories: [service_recovery]
  queues:
    categories: [backend_state_machine]
  scheduling_parallelism:
    categories: [validation_runner, backend_state_machine]
  retries_backoff_circuit_breakers:
    categories: [backend_state_machine, service_recovery]
  validation_test_runners:
    categories: [validation_runner]
  watchdogs:
    categories: [runtime_service, service_recovery]
  journal_consumers:
    categories: [runtime_service, backend_state_machine]
  auth_session_device_registration:
    categories: [backend_api, backend_state_machine]
  ui_live_state_coordination:
    categories: [frontend_state_machine, browser_visible_behavior]
  notification_toast_root_cause_state:
    categories: [frontend_state_machine, browser_visible_behavior]

categories:
  docs_only:
    required:
      summary_validation: true
    commands:
      - node ai/runtime/dist/cli.js summary validate --chunk <chunk> --json
    override_allowed: true
  report_only:
    required:
      summary_validation: true
      governance_validation: conditional
    commands:
      - node ai/runtime/dist/cli.js summary validate --chunk <chunk> --json
    override_allowed: true
  backend_api:
    required:
      backend_e2e: conditional
      full_validation: true
    commands:
      - yarn test:backend
      - yarn workspace backend test:e2e
      - node ai/runtime/dist/cli.js validate --tier chunk --chunk <chunk>
    override_allowed: false
  frontend_ui:
    required:
      frontend_component_or_service_tests: true
      browser_proof: conditional
      architecture_drift_check: conditional
    commands:
      - node ai/runtime/dist/cli.js testing frontend-specs --include <spec-path> --json
      - node ai/runtime/dist/cli.js testing runtime-action-panel-browser-smoke --chunk-id <chunk> --json
    override_allowed: false
  frontend_state_machine:
    required:
      research_checkpoint: true
      state_model: true
      deterministic_transition_tests: true
      forbidden_transition_tests: true
      adversarial_sequence_tests: true
      frontend_component_or_service_tests: true
      browser_proof: true
      architecture_drift_check: true
      final_clean_pass: true
    commands:
      - node ai/runtime/dist/cli.js testing frontend-specs --include <state-machine-spec> --json
      - node ai/runtime/dist/cli.js testing runtime-action-panel-browser-smoke --chunk-id <chunk> --json
    acceptance_mapping:
      - requirement: restored_toast_clears
        proof: browser_proof + deterministic_transition_tests
      - requirement: no_stale_message_rollback
        proof: frontend_component_or_service_tests
    override_allowed: false
  backend_state_machine:
    required:
      research_checkpoint: true
      state_model: true
      deterministic_transition_tests: true
      forbidden_transition_tests: true
      adversarial_sequence_tests: conditional
      full_validation: true
    commands:
      - node ai/runtime/dist/cli.js validate --tier chunk --chunk <chunk>
    override_allowed: false
  runtime_service:
    required:
      research_checkpoint: conditional
      full_validation: true
      architecture_drift_check: conditional
    commands:
      - node ai/runtime/dist/cli.js validate --tier chunk --chunk <chunk>
    override_allowed: false
  socket_live_update:
    required:
      research_checkpoint: true
      frontend_component_or_service_tests: true
      browser_proof: true
      architecture_drift_check: true
      final_clean_pass: true
    commands:
      - node ai/runtime/dist/cli.js testing frontend-specs --include <socket-or-refetch-spec> --json
      - node ai/runtime/dist/cli.js testing runtime-action-panel-browser-smoke --chunk-id <chunk> --json
    override_allowed: false
  browser_visible_behavior:
    required:
      browser_proof: true
      frontend_component_or_service_tests: conditional
      final_clean_pass: true
    commands:
      - node ai/runtime/dist/cli.js testing runtime-action-panel-browser-smoke --chunk-id <chunk> --json
    override_allowed: false
  lifecycle_authority:
    required:
      governance_validation: true
      full_validation: true
    commands:
      - node ai/runtime/dist/cli.js validate-governance --mode governance-core --json
      - node ai/runtime/dist/cli.js validate --tier chunk --chunk <chunk>
    override_allowed: false
  approval_dispatcher:
    required:
      governance_validation: true
      full_validation: true
    commands:
      - node ai/runtime/dist/cli.js validate-governance --mode governance-core --json
      - node ai/runtime/dist/cli.js validate --tier chunk --chunk <chunk>
    override_allowed: false
  service_recovery:
    required:
      research_checkpoint: true
      deterministic_transition_tests: true
      forbidden_transition_tests: true
      backend_e2e: conditional
      browser_proof: true
      full_validation: true
      final_clean_pass: true
    commands:
      - node ai/runtime/dist/cli.js testing service-resurrection-smoke --target frontend --json
      - node ai/runtime/dist/cli.js testing runtime-action-panel-browser-smoke --unplanned-resurrection-proof --json
    acceptance_mapping:
      - requirement: planned_vs_unplanned_classification
        proof: deterministic_transition_tests + browser_proof
    override_allowed: false
  validation_runner:
    required:
      research_checkpoint: conditional
      governance_validation: true
      full_validation: true
    commands:
      - node ai/runtime/dist/cli.js validation execution-plan --profile default --tier chunk --json
      - node ai/runtime/dist/cli.js validate --tier chunk --chunk <chunk>
    override_allowed: false
  work_registration:
    required:
      work_registration_visibility: true
      full_validation: true
      browser_proof: conditional
      final_clean_pass: conditional
    commands:
      - node ai/runtime/dist/cli.js testing work-registration-concurrency-smoke --chunk <chunk> --json
      - node ai/runtime/dist/cli.js testing runtime-action-panel-browser-smoke --role-work-matrix-proof --json
    override_allowed: false
  architecture_refactor:
    required:
      architecture_drift_check: true
      governance_validation: conditional
      full_validation: true
    commands:
      - node ai/runtime/dist/cli.js validate-governance --mode governance-core --json
      - node ai/runtime/dist/cli.js validate --tier chunk --chunk <chunk>
    override_allowed: false

inference_rules:
  - category: validation_runner
    title_patterns:
      - QA Test Requirement Resolver
      - Behavior Proof Gate
      - validation
      - test requirement
  - category: lifecycle_authority
    title_patterns:
      - lifecycle
      - authority
      - approval
      - dispatcher
  - category: work_registration
    title_patterns:
      - work registration
      - work visibility
  - category: frontend_state_machine
    title_patterns:
      - state model
      - state-machine
      - connection/recovery
      - toast
  - category: service_recovery
    title_patterns:
      - recovery
      - resurrection
      - restart
  - category: socket_live_update
    title_patterns:
      - socket
      - live update
  - category: frontend_ui
    path_prefixes:
      - apps/frontend/
  - category: backend_api
    path_prefixes:
      - apps/backend/
