timmy-config/playbooks/fleet-guardrails.yaml

# fleet-guardrails.yaml
# =====================
# Enforceable behaviour boundaries for every agent in the Timmy fleet.
# Consumed by task_gate.py (pre/post checks) and the orchestrator's
# dispatch loop. Every rule here is testable — no aspirational prose.
#
# Ref: SOUL.md "grounding before generation", Five Wisdoms #345

name: fleet-guardrails
version: "1.0.0"
description: >
  Behaviour constraints that apply to ALL agents regardless of role.
  These are the non-negotiable rules that task_gate.py enforces
  before an agent may pick up work and after it claims completion.

# ─── UNIVERSAL CONSTRAINTS ───────────────────────────────────────

constraints:

  # 1. Lane discipline — agents must stay in their lane
  lane_enforcement:
    enabled: true
    source: playbooks/agent-lanes.json
    on_violation: block_and_notify
    description: >
      An agent may only pick up issues tagged for its lane.
      Cross-lane work requires explicit Timmy approval via
      issue comment containing 'LANE_OVERRIDE: <agent>'.

  # 2. Branch hygiene — no orphan branches
  branch_hygiene:
    enabled: true
    max_branches_per_agent: 3
    stale_branch_days: 7
    naming_pattern: "{agent}/{issue_number}-{slug}"
    on_violation: warn_then_block
    description: >
      Agents must follow branch naming conventions and clean up
      after merge. No agent may have more than 3 active branches.

  # 3. Issue ownership — no silent takeovers
  issue_ownership:
    enabled: true
    require_assignment_before_work: true
    max_concurrent_issues: 2
    on_violation: block_and_notify
    description: >
      An agent must be assigned to an issue before creating a
      branch or PR. No agent may work on more than 2 issues
      simultaneously to prevent context-switching waste.

  # 4. PR quality — minimum bar before review
  pr_quality:
    enabled: true
    require_linked_issue: true
    require_passing_ci: true
    max_files_changed: 30
    max_diff_lines: 2000
    require_description: true
    min_description_length: 50
    on_violation: block_merge
    description: >
      Every PR must link an issue, pass CI, have a meaningful
      description, and stay within scope. Giant PRs get rejected.

  # 5. Grounding before generation — SOUL.md compliance
  grounding:
    enabled: true
    require_issue_read_before_branch: true
    require_existing_code_review: true
    require_soul_md_check: true
    soul_md_path: SOUL.md
    on_violation: block_and_notify
    description: >
      Before writing any code, the agent must demonstrate it has
      read the issue, reviewed relevant existing code, and checked
      SOUL.md for applicable doctrine. No speculative generation.

  # 6. Completion integrity — no phantom completions
  completion_checks:
    enabled: true
    require_test_evidence: true
    require_ci_green: true
    require_diff_matches_issue: true
    require_no_unrelated_changes: true
    on_violation: revert_and_notify
    description: >
      Post-task gate verifies the work actually addresses the
      issue. Agents cannot close issues without evidence.
      Unrelated changes in a PR trigger automatic rejection.

  # 7. Communication discipline — no noise
  communication:
    enabled: true
    max_comments_per_issue: 10
    require_structured_updates: true
    update_format: "status | what_changed | what_blocked | next_step"
    prohibit_empty_updates: true
    on_violation: warn
    description: >
      Issue comments must be structured and substantive.
      Status-only comments without content are rejected.
      Agents should update, not narrate.

  # 8. Resource awareness — no runaway costs
  resource_limits:
    enabled: true
    max_api_calls_per_task: 100
    max_llm_tokens_per_task: 500000
    max_task_duration_minutes: 60
    on_violation: kill_and_notify
    description: >
      Hard limits on compute per task. If an agent hits these
      limits, the task is killed and flagged for human review.
      Prevents infinite loops and runaway API spending.

# ─── ESCALATION POLICY ───────────────────────────────────────────

escalation:
  channels:
    - gitea_issue_comment
    - discord_webhook
  severity_levels:
    warn:
      action: post_comment
      notify: agent_only
    block:
      action: prevent_action
      notify: agent_and_orchestrator
    block_and_notify:
      action: prevent_action
      notify: agent_orchestrator_and_timmy
    kill_and_notify:
      action: terminate_task
      notify: all_including_alexander
    revert_and_notify:
      action: revert_changes
      notify: agent_orchestrator_and_timmy

# ─── AUDIT TRAIL ─────────────────────────────────────────────────

audit:
  enabled: true
  log_path: logs/guardrail-violations.jsonl
  retention_days: 90
  fields:
    - timestamp
    - agent
    - constraint
    - violation_type
    - issue_number
    - action_taken
    - resolution

# ─── OVERRIDES ───────────────────────────────────────────────────

overrides:
  # Only Timmy or Alexander can override guardrails
  authorized_overriders:
    - Timmy
    - Alexander
  override_mechanism: >
    Post a comment on the issue with the format:
    GUARDRAIL_OVERRIDE: <constraint_name> REASON: <explanation>
  override_expiry_hours: 24
  require_post_override_review: true