Rules and code

# Vallum policy: the machine-checkable half of the Rulebook. Protected path.
# Enforcement always reads this file from the default branch (FR-RULE-4).

owners: [ansh-varshney]          # humans who own the rules; Merge Desk approves as the owner
project: { id: 87894346, default_branch: main }

labels:
  opt_in: vallum                 # Layer 1: a member adds this label; Layer 2: member-only triggers add it
  ready: "vallum::ready"
  blocked: "vallum::blocked"
  stalled: "vallum::stalled"
  needs_human: "vallum::needs-human"
  ledger: "vallum::ledger"
  incident: "vallum::incident"
  paused: "vallum::paused"
  fix: "vallum-fix"                # not scoped: GitLab keeps one vallum:: label per item, and these describe the change, not its state
  housekeeping: "vallum-housekeeping"
  override: "vallum-override"

demo: true                       # demo watch times, sample sizes and 60-minute windows

releases:   { one_at_a_time: true, max_fix_attempts: 2, max_review_rounds: 2, max_rebase_fixes: 2, max_flow_runs_per_issue: 3 }
promises:   { agents_may: [add, tighten], watch_promises_expire: after_release }
at_risk:    rollback                         # safe default, never "hold and ask an agent"

tiers:
  core:         { target: 0.999, steps: [1, 10, 50, 100], watch_min: 10, demo_watch_min: 2,   yellow: none, red_below: 0.50, recover_above: 0.65 }
  standard:     { target: 0.995, steps: [10, 50, 100],    watch_min: 5,  demo_watch_min: 1,   yellow_below: 0.50, yellow_extra_step: 25, red_below: 0.10, recover_above: 0.25 }
  experimental: { target: 0.990, steps: [25, 100],        watch_min: 2,  demo_watch_min: 0.5, red_below: null }

circuit_breaker: { rollbacks: 3, within_hours: 6 }
never_allowed: [payments, auth_rewrite, delete_user_data, legal_text, secrets]
windows:    { production_days: 30, demo_minutes: 60 }

protected_paths:
  - vallum/
  - control/                     # the control room (status site): Vallum's own instrument
  - .gitlab-ci.yml
  - .gitlab/duo/
  - skills/
  - AGENTS.md
  - CODEOWNERS
  - promises/service.yaml
  - promises/learned/
  - docs/vallum/GUIDELINES.md
  - docs/vallum/CODEMAP.md       # generated by code; changed only by the housekeeping MR (made with the owner's account)
  - docs/vallum/roles/
core_paths: [app/main.py, app/store.py, app/security.py]   # touching these makes a change Core

gate:
  agent_verdicts_required: true    # rule 9: Reviewer approves and the Inspector says "matches" (Layer 2)
  yellow_max_changed_lines: 200

provenance:
  allow_owner_push: false          # demo and after: only Merge Desk merges deploy (true during the build phase: owner pushes deployed, recorded as overrides)

merge_desk: { pipeline_wait_min: 20, rebase_wait_s: 180 }

judge:
  min_samples:      { speed: 300, reliability: 500 }
  demo_min_samples: { speed: 100, reliability: 200 }
  mr_samples: 40                   # localhost load per metric promise in MR pipelines
  worse_than_old: 0.20             # a metric is broken only if also 20% worse than the old revision
  at_risk_margin: 0.05             # within 5% of the limit at the end of a step counts as at risk
  step_retry_s: 5
  tick_s: 10
  warmup_s: 10                  # each revision's first seconds of traffic at a step are not judged (cold start, switch landing)

simulate:
  links: 120                       # persistent "real" links, popularity follows a Zipf curve
  base_rps: 20
  max_rps: 100                     # one CI runner sends ~107 req/s cleanly; at 133 every route on both revisions took 3-4 s (r-0032)
  step0_requests: 300
  mix: { "GET /r/{code}": 0.85, "GET /api/links/{code}": 0.08, "GET /health": 0.05, "POST /api/links": 0.02 }

watchdog:
  deadlines_min: { planning: 15, building: 30, reviewing: 15, gated: 10, merged: 10, driving_extra: 10, door_a_no_mr: 45 }

allowance:                       # B10: mistake allowance per tier and app-wide, over windows.demo_minutes
  app_target: 0.995
  behavior_break_cost: 0.05      # a broken live behavior promise spends 5% of that tier's allowance
  standard_yellow_exit: 0.60     # hysteresis: Standard leaves Yellow above 60% (enters below 50%)
  patrol_visit_seconds: 30       # each Live Patrol run sends simulated visitors for this long
  slow_factor: 2                 # a visit slower than 2x its route's speed limit counts as a bad visit
  min_allowed_bad: 20            # noise floor: a window always allows at least 20 bad visits (patrol traffic shows ~0.2% network blips)

cockpit:
  prefix: "@vallum"              # exact commands, carried out by code for members only (B23); the Cockpit bot's name works too
  min_access: 30                 # Developer
  poll_s: 15                     # listen mode: how often code looks for new commands
  rescan_minutes: 30             # every scan re-reads this window (replica lag); each command still runs once
  listen_after_command_min: 20   # after any command, keep listening this long (commands come in bursts)
  listen_max_min: 180            # longest `@vallum listen <minutes>`
  desk_kick_min_s: 120           # listen mode re-runs the Merge Desk at once when a Vallum MR changes, at most this often
  job_listen_max_min: 25         # one Live Patrol job listens at most this long; jobs overlap because schedules can start late

agents:
  start_via_triggers: true       # code starts agents by member-only actions (namespace credits), API as fallback
  combined_guardians: false      # true: one guardian call drafts every required type (cheaper)

credits:
  daily_code_started_sessions: 40   # more than this in a day turns Safe mode on (credit guard, FR-WD-4)

cloud_run: { service: vallum, status_service: vallum-status, region: us-central1, max_scale_cap: 5, project: vallum-512306 }