draft-board 0.1.0-beta.0

package/app/backend/tests/test_webhook_service.py

@@ -0,0 +1,184 @@
+"""Tests for webhook notification service."""
+
+import hashlib
+import hmac
+import json
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from app.services.webhook_service import _build_payload, _sign_payload, fire_webhooks
+
+
+def test_build_payload():
+    payload = _build_payload(
+        event="ticket.transitioned",
+        ticket_id="t1",
+        ticket_title="Fix bug",
+        board_id="b1",
+        from_state="proposed",
+        to_state="approved",
+        actor_type="human",
+        actor_id="user1",
+        reason="Looks good",
+    )
+    assert payload["event"] == "ticket.transitioned"
+    assert payload["ticket"]["id"] == "t1"
+    assert payload["ticket"]["from_state"] == "proposed"
+    assert payload["ticket"]["to_state"] == "approved"
+    assert payload["actor"]["type"] == "human"
+    assert payload["reason"] == "Looks good"
+    assert "timestamp" in payload
+
+
+def test_sign_payload():
+    data = b'{"test": true}'
+    secret = "mysecret"
+    sig = _sign_payload(data, secret)
+    expected = hmac.new(secret.encode(), data, hashlib.sha256).hexdigest()
+    assert sig == expected
+
+
+@pytest.mark.asyncio
+async def test_fire_webhooks_empty():
+    """No webhooks = no-op."""
+    await fire_webhooks(
+        [],
+        ticket_id="t1",
+        ticket_title="Test",
+        board_id="b1",
+        from_state="proposed",
+        to_state="approved",
+        actor_type="human",
+        actor_id=None,
+        reason=None,
+    )
+
+
+@pytest.mark.asyncio
+async def test_fire_webhooks_posts_to_url():
+    """Webhook sends POST with correct payload."""
+    mock_response = AsyncMock()
+    mock_response.status_code = 200
+
+    with patch("app.services.webhook_service.httpx.AsyncClient") as mock_client_cls:
+        mock_client = AsyncMock()
+        mock_client.post.return_value = mock_response
+        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+        mock_client.__aexit__ = AsyncMock(return_value=False)
+        mock_client_cls.return_value = mock_client
+
+        webhooks = [{"id": "w1", "url": "https://example.com/hook", "events": ["*"]}]
+        await fire_webhooks(
+            webhooks,
+            ticket_id="t1",
+            ticket_title="Fix bug",
+            board_id="b1",
+            from_state="proposed",
+            to_state="approved",
+            actor_type="human",
+            actor_id="user1",
+            reason=None,
+        )
+
+        mock_client.post.assert_called_once()
+        call_args = mock_client.post.call_args
+        assert call_args[1]["headers"]["Content-Type"] == "application/json"
+        payload = json.loads(call_args[1]["content"])
+        assert payload["event"] == "ticket.transitioned"
+        assert payload["ticket"]["id"] == "t1"
+
+
+@pytest.mark.asyncio
+async def test_fire_webhooks_with_secret():
+    """Webhook includes HMAC signature when secret is set."""
+    mock_response = AsyncMock()
+    mock_response.status_code = 200
+
+    with patch("app.services.webhook_service.httpx.AsyncClient") as mock_client_cls:
+        mock_client = AsyncMock()
+        mock_client.post.return_value = mock_response
+        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+        mock_client.__aexit__ = AsyncMock(return_value=False)
+        mock_client_cls.return_value = mock_client
+
+        webhooks = [
+            {
+                "id": "w1",
+                "url": "https://example.com/hook",
+                "events": ["*"],
+                "secret": "s3cret",
+            }
+        ]
+        await fire_webhooks(
+            webhooks,
+            ticket_id="t1",
+            ticket_title="Test",
+            board_id="b1",
+            from_state="proposed",
+            to_state="approved",
+            actor_type="agent",
+            actor_id=None,
+            reason=None,
+        )
+
+        call_args = mock_client.post.call_args
+        headers = call_args[1]["headers"]
+        assert "X-Webhook-Signature" in headers
+        assert headers["X-Webhook-Signature"].startswith("sha256=")
+
+
+@pytest.mark.asyncio
+async def test_fire_webhooks_event_filter():
+    """Webhook with non-matching event filter is skipped."""
+    with patch("app.services.webhook_service.httpx.AsyncClient") as mock_client_cls:
+        mock_client = AsyncMock()
+        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+        mock_client.__aexit__ = AsyncMock(return_value=False)
+        mock_client_cls.return_value = mock_client
+
+        webhooks = [
+            {
+                "id": "w1",
+                "url": "https://example.com/hook",
+                "events": ["ticket.deleted"],
+            }
+        ]
+        await fire_webhooks(
+            webhooks,
+            ticket_id="t1",
+            ticket_title="Test",
+            board_id="b1",
+            from_state="proposed",
+            to_state="approved",
+            actor_type="human",
+            actor_id=None,
+            reason=None,
+        )
+
+        mock_client.post.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_fire_webhooks_error_does_not_raise():
+    """Webhook delivery failure is swallowed (best-effort)."""
+    with patch("app.services.webhook_service.httpx.AsyncClient") as mock_client_cls:
+        mock_client = AsyncMock()
+        mock_client.post.side_effect = Exception("Connection refused")
+        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+        mock_client.__aexit__ = AsyncMock(return_value=False)
+        mock_client_cls.return_value = mock_client
+
+        webhooks = [{"id": "w1", "url": "https://example.com/hook", "events": ["*"]}]
+        # Should not raise
+        await fire_webhooks(
+            webhooks,
+            ticket_id="t1",
+            ticket_title="Test",
+            board_id="b1",
+            from_state="proposed",
+            to_state="approved",
+            actor_type="human",
+            actor_id=None,
+            reason=None,
+        )

package/app/backend/tickets_output.json

@@ -0,0 +1,59 @@
+{
+  "tickets": [
+    {
+      "title": "Add comprehensive API endpoint test coverage",
+      "description": "Create integration tests for all API endpoints across routers (boards, tickets, goals, jobs, revisions, etc.). Currently only 6 test files exist covering limited functionality. Tests should cover:\n- CRUD operations for all resources\n- State transitions and validation\n- Error cases and edge cases\n- Board-scoped authorization checks\n- Bulk operations (accept, priority updates)\n\nAcceptance criteria:\n- Test coverage >80% for all routers\n- All endpoints have at least happy path and error case tests\n- Tests use pytest fixtures from conftest.py\n- Tests verify database state changes correctly",
+      "priority_bucket": "P1",
+      "priority_rationale": "High priority - tests are essential for maintaining code quality and preventing regressions as the codebase grows. Current test coverage is minimal.",
+      "verification": [
+        "pytest tests/ --cov=app --cov-report=term-missing",
+        "pytest tests/ -v --tb=short"
+      ],
+      "notes": "Focus on testing routers/ directory first. Use async test patterns with AsyncSession fixtures. Consider using httpx.AsyncClient for API endpoint testing."
+    },
+    {
+      "title": "Add comprehensive API documentation and README",
+      "description": "Create detailed documentation for the Smart Kanban backend API including:\n- README.md with setup instructions, architecture overview, and development guide\n- API endpoint documentation (OpenAPI/Swagger is auto-generated but needs enhancement)\n- Database schema documentation\n- Environment variable reference\n- Deployment guide\n- Contributing guidelines\n\nAcceptance criteria:\n- README.md exists with clear setup instructions\n- All environment variables documented in ENV_SETUP.md or README\n- API endpoint examples provided\n- Architecture diagram or description included\n- Database migration guide documented",
+      "priority_bucket": "P2",
+      "priority_rationale": "Medium priority - documentation improves developer onboarding and maintainability, but doesn't block functionality.",
+      "verification": [
+        "test -f README.md && grep -q 'setup\\|installation' README.md",
+        "grep -r 'DATABASE_URL\\|FRONTEND_URL' .env.example README.md ENV_SETUP.md"
+      ],
+      "notes": "Reference existing ENV_SETUP.md. Include examples from CURL_EXAMPLES.md. Document the board-scoped architecture and permission model."
+    },
+    {
+      "title": "Add database migration validation and rollback tests",
+      "description": "Implement validation for Alembic migrations to prevent data loss and ensure migrations are reversible:\n- Add migration tests that verify up/down migrations work correctly\n- Validate that migrations don't drop columns without data migration\n- Test migration rollback scenarios\n- Add pre-migration checks for critical schema changes\n- Document migration best practices\n\nAcceptance criteria:\n- Test suite validates all migrations can be applied and rolled back\n- Migrations include data migration steps where needed\n- Pre-migration validation catches dangerous operations\n- Migration guide documents rollback procedures",
+      "priority_bucket": "P1",
+      "priority_rationale": "High priority - database migrations can cause data loss if not properly tested. Current 12 migration files need validation.",
+      "verification": [
+        "alembic upgrade head && alembic downgrade -1 && alembic upgrade head",
+        "pytest tests/test_migrations.py -v"
+      ],
+      "notes": "Create tests/test_migrations.py. Use Alembic's testing utilities. Focus on migrations that modify or drop columns (especially in ticket, job, goal tables)."
+    },
+    {
+      "title": "Implement structured logging and request tracing",
+      "description": "Enhance logging throughout the application with structured logging and request tracing:\n- Replace print statements and basic logger calls with structured logging\n- Add request ID tracking for tracing requests through the system\n- Implement correlation IDs for Celery tasks\n- Add performance logging for slow operations\n- Create log aggregation configuration (JSON format for production)\n\nAcceptance criteria:\n- All services use structured logging with context\n- Request IDs propagate through FastAPI → services → Celery tasks\n- Slow operations (>1s) are logged with timing\n- Logs include board_id, ticket_id, goal_id for traceability\n- Production logging uses JSON format",
+      "priority_bucket": "P2",
+      "priority_rationale": "Medium priority - improves debugging and observability but doesn't block core functionality. Current logging is basic.",
+      "verification": [
+        "grep -r 'print(' app/ | wc -l",
+        "python -c 'import logging; logging.basicConfig(); logging.info({\"test\": \"structured\"})'"
+      ],
+      "notes": "Use structlog or python-json-logger. Add middleware for request ID generation. Update worker.py to include correlation IDs in Celery tasks."
+    },
+    {
+      "title": "Add health check endpoints and monitoring metrics",
+      "description": "Enhance the existing /health endpoint and add monitoring capabilities:\n- Expand /health to check database connectivity, Redis availability, Celery worker status\n- Add /metrics endpoint for Prometheus-style metrics\n- Track key metrics: job queue depth, ticket state distribution, error rates\n- Add readiness and liveness probes for Kubernetes deployment\n- Implement health check for board repo_root accessibility\n\nAcceptance criteria:\n- /health endpoint returns detailed status of all dependencies\n- /metrics endpoint exposes Prometheus-compatible metrics\n- Health checks fail fast if critical dependencies unavailable\n- Metrics track: active jobs, tickets by state, API request rates, error rates",
+      "priority_bucket": "P2",
+      "priority_rationale": "Medium priority - monitoring improves production reliability and debugging, but basic health check already exists.",
+      "verification": [
+        "curl http://localhost:8000/health | jq '.status'",
+        "curl http://localhost:8000/metrics | grep -q 'ticket_state_total'"
+      ],
+      "notes": "Use prometheus-fastapi-instrumentator or similar. Check database, Redis, and Celery broker connectivity. Validate board repo_root paths are accessible."
+    }
+  ]
+}

package/app/backend/user_management_tickets.json

@@ -0,0 +1,50 @@
+{
+  "tickets": [
+    {
+      "title": "Create User model and database migration",
+      "description": "Create the User SQLAlchemy model with fields: id (UUID), email (unique, indexed), username (unique, indexed), hashed_password, is_active (default True), is_superuser (default False), created_at, updated_at. Create Alembic migration file following the pattern in alembic/versions/012_add_boards_table.py. The User model should extend app.models.base.Base and follow existing model patterns (e.g., app/models/ticket.py). Add proper indexes on email and username for performance.\n\nAcceptance criteria:\n- User model exists in app/models/user.py\n- Migration file created in alembic/versions/013_add_users_table.py\n- Migration can be applied successfully (alembic upgrade head)\n- Model includes all required fields with proper types and constraints\n- Email and username have unique constraints and indexes",
+      "priority_bucket": "P0",
+      "priority_rationale": "Foundation for all authentication features - without users, nothing else works",
+      "verification": [
+        "alembic upgrade head",
+        "python -c 'from app.models.user import User; print(\"User model imported successfully\")'"
+      ],
+      "notes": "Follow existing model patterns - use String(36) for UUIDs, DateTime with server_default=func.now() for timestamps. Use batch_alter_table for SQLite compatibility if needed."
+    },
+    {
+      "title": "Implement JWT authentication system with login endpoint",
+      "description": "Implement JWT-based authentication: (1) Add dependencies: python-jose[cryptography] and passlib[bcrypt] to requirements.txt, (2) Create app/auth/security.py with functions: hash_password(), verify_password(), create_access_token(), decode_access_token(), (3) Create app/auth/dependencies.py with get_current_user() dependency that validates JWT tokens from Authorization header, (4) Create POST /auth/login endpoint in app/routers/auth.py that accepts email/username and password, verifies credentials, and returns JWT access token, (5) Add proper error handling for invalid credentials (401), (6) Configure JWT_SECRET_KEY and JWT_ALGORITHM in environment/config.\n\nAcceptance criteria:\n- POST /auth/login returns 200 with access_token on valid credentials\n- POST /auth/login returns 401 on invalid credentials\n- JWT tokens contain user_id and expire after configured time (default 24h)\n- get_current_user dependency raises HTTPException 401 on invalid/missing token\n- Passwords are hashed with bcrypt before storage\n- OpenAPI docs show login endpoint with proper request/response schemas",
+      "priority_bucket": "P0",
+      "priority_rationale": "Security-critical - authentication is required before any protected endpoints can work",
+      "verification": [
+        "curl -X POST http://localhost:8000/auth/login -H 'Content-Type: application/json' -d '{\"email\":\"test@example.com\",\"password\":\"test123\"}' | jq .access_token",
+        "python -c 'from app.auth.security import hash_password, verify_password; h=hash_password(\"test\"); assert verify_password(\"test\", h)'"
+      ],
+      "notes": "Use HS256 algorithm for JWT. Store JWT_SECRET_KEY in environment variables. Follow FastAPI dependency injection patterns like get_db(). Reference app/routers/tickets.py for router patterns."
+    },
+    {
+      "title": "Create user CRUD REST endpoints",
+      "description": "Create REST API endpoints for user management: (1) POST /users (create user) - requires email, username, password, returns user without password, (2) GET /users (list users) - returns paginated list, (3) GET /users/{user_id} (get user by ID), (4) PUT /users/{user_id} (update user - email, username, is_active), (5) DELETE /users/{user_id} (soft delete by setting is_active=False). Create app/schemas/user.py with UserCreate, UserUpdate, UserResponse schemas. Create app/services/user_service.py following patterns from app/services/ticket_service.py. Add proper validation, error handling (404 for not found, 409 for duplicate email/username), and ensure passwords are never returned in responses.\n\nAcceptance criteria:\n- All CRUD endpoints exist and are registered in app/main.py\n- POST /users creates user with hashed password\n- GET /users returns list without password fields\n- PUT /users/{user_id} updates user fields\n- DELETE /users/{user_id} sets is_active=False\n- All endpoints return proper HTTP status codes (201, 200, 404, 409)\n- Validation errors return 422 with detail messages\n- OpenAPI documentation is complete for all endpoints",
+      "priority_bucket": "P1",
+      "priority_rationale": "Core feature requirement - user management API is the main deliverable",
+      "verification": [
+        "curl -X POST http://localhost:8000/users -H 'Content-Type: application/json' -d '{\"email\":\"user@example.com\",\"username\":\"testuser\",\"password\":\"secure123\"}' | jq",
+        "curl http://localhost:8000/users | jq '.total'",
+        "curl http://localhost:8000/docs | grep -q 'users'"
+      ],
+      "notes": "Follow existing router patterns from app/routers/tickets.py. Use Pydantic schemas for validation. Ensure UserResponse excludes password field using model_config. Handle duplicate email/username with 409 Conflict status."
+    },
+    {
+      "title": "Implement role-based access control (RBAC)",
+      "description": "Add role-based access control: (1) Create app/models/enums.py addition or new Role enum with values: ADMIN, USER, VIEWER, (2) Add role column to User model (default USER), create migration, (3) Create app/auth/permissions.py with decorators/dependencies: require_role(), require_admin(), (4) Protect user CRUD endpoints: POST/PUT/DELETE require ADMIN role, GET /users/{user_id} allows same user or ADMIN, GET /users requires ADMIN, (5) Update get_current_user dependency to include role in token payload, (6) Add role to UserResponse schema, (7) Create POST /users/{user_id}/change-role endpoint (admin only) to update user roles.\n\nAcceptance criteria:\n- Role enum exists with ADMIN, USER, VIEWER values\n- User model has role field with default USER\n- require_role() dependency restricts endpoints by role\n- Regular users can only view/edit their own profile\n- Admin users can manage all users\n- JWT tokens include role claim\n- POST /users/{user_id}/change-role endpoint exists and requires ADMIN\n- Unauthorized access returns 403 Forbidden",
+      "priority_bucket": "P1",
+      "priority_rationale": "Important security feature for multi-user systems, but can be implemented after basic auth",
+      "verification": [
+        "curl -X GET http://localhost:8000/users -H 'Authorization: Bearer <user_token>' | grep -q '403'",
+        "curl -X GET http://localhost:8000/users -H 'Authorization: Bearer <admin_token>' | jq '.total'",
+        "python -c 'from app.auth.permissions import require_role; print(\"Permissions module imported\")'"
+      ],
+      "notes": "Use FastAPI dependencies for role checking. Follow middleware patterns but prefer dependency injection. Update JWT token creation to include role. Reference existing authorization patterns in app/routers/tickets.py (board_id checks) for inspiration."
+    }
+  ]
+}

package/app/draft.yaml

@@ -0,0 +1,313 @@
+# Draft Configuration
+# This file configures execution and verification pipelines for Draft.
+
+# =============================================================================
+# PROJECT CONFIGURATION
+# =============================================================================
+
+project:
+  # Path to the repository root (relative to this config file or absolute)
+  repo_root: "."
+
+# =============================================================================
+# EXECUTION CONFIGURATION
+# =============================================================================
+# Settings for the execute job that implements ticket changes using AI code tools.
+#
+# Executor Types:
+#   - Claude CLI (headless): Runs automatically, can implement changes without user
+#   - Cursor CLI (interactive): Opens editor, transitions to needs_human for manual work
+#
+# State Transitions:
+#   - Headless success with diff → verifying
+#   - Headless success with NO diff → blocked (reason: no changes)
+#   - Headless failure → blocked
+#   - Interactive (Cursor) → needs_human immediately
+#   - YOLO refused (empty allowlist) → needs_human with explanation
+
+execute_config:
+  # Timeout for executor CLI in seconds (default: 600 = 10 minutes)
+  timeout: 600
+
+  # Preferred executor CLI
+  # Options:
+  #   - "claude": Claude Code CLI (recommended for automation, headless)
+  #   - "cursor": Cursor CLI (interactive, opens editor for human)
+  preferred_executor: "claude"
+
+  # Maximum concurrent execute jobs (default: 1 = sequential)
+  # Set higher to execute independent tickets in parallel.
+  # Dependent tickets (blocked_by) are always executed sequentially.
+  max_parallel_jobs: 1
+
+  # ---------------------------------------------------------------------------
+  # YOLO MODE - DANGEROUS: Skip permission prompts
+  # ---------------------------------------------------------------------------
+  # When enabled AND allowlist is non-empty, Claude CLI runs with
+  # --dangerously-skip-permissions. This allows the AI to run any command
+  # without asking for approval.
+  #
+  # ⚠️  SECURITY WARNING ⚠️
+  # Only enable this if you understand the risks:
+  #   - AI can run ANY shell command without confirmation
+  #   - Prompt injection attacks could execute malicious code
+  #   - Network access, file deletion, etc. are all unrestricted
+  #
+  # Safety Policy (enforced by worker):
+  #   - If yolo_mode=true BUT yolo_allowlist is empty → REFUSES to run YOLO
+  #   - Transitions to needs_human with explanation
+  #   - You MUST explicitly list trusted paths in yolo_allowlist
+  #   - Only runs inside isolated worktrees (path validation enforced)
+  #   - Never runs on main/master/develop branches
+  #
+  # Default: false (permissioned mode - safer)
+  yolo_mode: true
+
+  # REQUIRED when yolo_mode=true: list of trusted repo paths
+  # If yolo_mode is true but this is empty, execution REFUSES for safety.
+  # This prevents "I turned on YOLO and forgot" accidents.
+  # Example: ["/Users/me/trusted-repo", "/home/ci/project"]
+  yolo_allowlist: []
+
+# =============================================================================
+# EXECUTOR PROFILES
+# =============================================================================
+# Named profiles with per-executor overrides. Use these to configure different
+# execution strategies (e.g., fast vs thorough, different models, timeouts).
+#
+# Select a profile when running a ticket:
+#   POST /tickets/{id}/run?executor_profile=fast
+#
+# Example:
+#   executor_profiles:
+#     fast:
+#       executor_type: claude
+#       timeout: 300
+#       extra_flags: ["--model", "claude-haiku-4-5-20251001"]
+#     thorough:
+#       executor_type: claude
+#       timeout: 1200
+#       extra_flags: ["--model", "claude-opus-4-6"]
+#     codex-auto:
+#       executor_type: codex
+#       timeout: 600
+#       extra_flags: ["--full-auto"]
+
+executor_profiles: {}
+
+# =============================================================================
+# VERIFICATION CONFIGURATION
+# =============================================================================
+# Settings for the verify job that validates ticket implementations.
+#
+# State Transitions:
+#   - All commands pass → needs_human (awaiting user review/approval)
+#   - Any command fails → blocked
+#   - User approves revision → done
+
+verify_config:
+  # Commands to run during ticket verification
+  # Each command is executed in the ticket's isolated worktree directory.
+  # Commands run sequentially; verification stops on first failure.
+  commands:
+    - "python -m pytest -q test_calculator.py"
+
+  # Note: After verification passes, tickets always go to 'needs_human' for review.
+  # Only when the user explicitly approves the revision does it move to 'done'.
+  # This ensures human oversight of all code changes before completion.
+
+  # Target state when verification fails (currently only "blocked" supported)
+  on_failure: "blocked"
+
+# =============================================================================
+# CLEANUP CONFIGURATION
+# =============================================================================
+# Controls automatic cleanup of worktrees and evidence files to prevent disk rot.
+# Use POST /maintenance/cleanup to trigger cleanup manually.
+
+cleanup_config:
+  # Delete worktree after successful merge
+  auto_cleanup_on_merge: true
+  # Delete worktrees older than this many days
+  worktree_ttl_days: 14
+  # Delete evidence files older than this many days  
+  evidence_ttl_days: 30
+  # Maximum number of active worktrees (for future use)
+  max_worktrees: 50
+
+# =============================================================================
+# MERGE CONFIGURATION
+# =============================================================================
+# Controls how worktree branches are merged back into the default branch.
+# Use POST /tickets/{id}/merge to trigger merge after approval.
+
+merge_config:
+  # Default merge strategy: "merge" or "rebase"
+  default_strategy: "merge"
+  # Pull --ff-only before merge to ensure we're up to date
+  pull_before_merge: true
+  # Delete the feature branch after successful merge
+  delete_branch_after_merge: true
+
+# =============================================================================
+# AUTONOMY CONFIGURATION
+# =============================================================================
+# Safety rails for full autonomy mode. When a goal has autonomy_enabled=true,
+# these settings control what the system is allowed to auto-approve.
+#
+# Individual gates (auto_approve_tickets, auto_approve_revisions, auto_merge,
+# auto_approve_followups) are set per-goal via the API.
+# These global settings define safety limits that apply to ALL autonomous goals.
+
+autonomy_config:
+  # Maximum diff lines allowed for auto-approval of revisions.
+  # Diffs larger than this require human review.
+  max_diff_lines: 500
+
+  # File patterns that trigger mandatory human review.
+  # If any file in the diff matches these patterns, auto-approval is blocked.
+  sensitive_file_patterns:
+    - "**/.env*"
+    - "**/*.pem"
+    - "**/*.key"
+    - "**/secrets/**"
+    - "**/credentials*"
+
+  # Require all verification commands to pass before auto-approving.
+  # When true (default), any verification failure blocks auto-approval.
+  require_verification_pass: true
+
+# =============================================================================
+# PLANNER CONFIGURATION
+# =============================================================================
+# Settings for the AI planner that automates workflow decisions.
+#
+# The planner runs in "tick" mode - each tick evaluates the board state and
+# takes one or more actions:
+#   - Pick next ticket: If PLANNED tickets exist and nothing is EXECUTING
+#   - Propose follow-ups: For BLOCKED tickets, generate follow-up ticket proposals
+#   - Generate reflections: For DONE tickets, create summary comments
+#
+# LLM is only used for follow-ups and reflections. Ticket selection is deterministic.
+
+planner_config:
+  # Agent CLI path for ticket generation (cursor-agent or claude)
+  # Auto-detected from PATH; set full path to override (e.g., "~/.local/bin/cursor-agent")
+  agent_path: "claude"
+
+  # LLM model for the planner.
+  # Default: "cli/claude" — uses the same Claude Code CLI as the executor (no API key needed).
+  # To use an API model instead, change in Settings > Executors or set here:
+  #   Direct Anthropic API:  "anthropic/claude-sonnet-4-5-20250929"  (requires ANTHROPIC_API_KEY)
+  #   AWS Bedrock:           "bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0"  (requires AWS credentials)
+  #   Bedrock inf. profile:  "bedrock/arn:aws:bedrock:us-east-2:...:inference-profile/..."
+  #   OpenAI:                "gpt-4o-mini" or "gpt-4o"  (requires OPENAI_API_KEY)
+  model: "cli/claude"
+
+  # Maximum tokens for LLM responses
+  max_tokens_reflection: 300
+  max_tokens_followup: 500
+
+  # Timeout for LLM API calls in seconds
+  timeout: 30
+
+  # ---------------------------------------------------------------------------
+  # SAFETY CAPS - Prevent runaway follow-up generation
+  # ---------------------------------------------------------------------------
+  # Follow-ups for blocked tickets can explode your backlog if uncapped.
+  # These limits ensure the planner doesn't spam your board.
+
+  # Maximum follow-up tickets for any single blocked ticket (total, ever)
+  max_followups_per_ticket: 2
+
+  # Maximum follow-up tickets created in one tick
+  max_followups_per_tick: 3
+
+  # Blocker reasons that should NOT trigger follow-ups
+  # These are typically prompt/requirements issues, not new tickets
+  skip_followup_reasons:
+    - "no changes produced"
+    - "no changes"
+    - "empty diff"
+
+  # Enable/disable specific planner features
+  features:
+    # Automatically pick and execute highest priority PLANNED ticket
+    # When false, tickets stay in "planned" until you click "Start Autopilot"
+    # When true, the periodic planner tick will automatically start executing planned tickets
+    auto_execute: false
+    # Generate follow-up ticket proposals for BLOCKED tickets
+    propose_followups: true
+    # Generate reflection summaries for DONE tickets
+    generate_reflections: true
+    # Validate generated tickets against codebase before creating them
+    # When true, the LLM checks if tickets are:
+    #   - Appropriate for the goal
+    #   - Not already implemented
+    #   - Relevant to the codebase
+    # Invalid tickets are filtered out and logged
+    validate_tickets: false  # Disabled for testing - agent output will generate all tickets
+
+  # ---------------------------------------------------------------------------
+  # UDAR AGENT CONFIGURATION (Experimental)
+  # ---------------------------------------------------------------------------
+  # UDAR (Understand-Decide-Act-Validate-Review) is a lean agent architecture
+  # for adaptive ticket generation. When enabled, it replaces the legacy
+  # single-shot ticket generator with a structured workflow that:
+  #   - Gathers codebase context deterministically (0 LLM calls)
+  #   - Generates tickets in batched LLM call (1 LLM call)
+  #   - Validates proposals deterministically (0 LLM calls)
+  #   - Can optionally re-plan after ticket completion (incremental)
+  #
+  # COST: 1-2 LLM calls per goal (vs legacy 1 call), but with better reasoning
+  udar:
+    # Enable UDAR agent for ticket generation (default: false for Phase 2 testing)
+    enabled: false
+
+    # Enable incremental replanning after ticket completion (default: false)
+    # When true, agent analyzes completed tickets and generates follow-ups
+    # Cost: ~1 LLM call per 5 completed tickets (batched)
+    enable_incremental_replanning: false
+
+    # Max self-correction iterations if validation fails (default: 1 to save quota)
+    max_self_correction_iterations: 1
+
+    # Enable optional LLM validation in Validate phase (default: false)
+    # When false, only deterministic validation is used (exact duplicate check, etc.)
+    # When true, adds LLM-based validation (+1 LLM call)
+    enable_llm_validation: false
+
+    # Incremental replanning settings (Phase 3)
+    # Batch size: Wait for this many completed tickets before analyzing (default: 5)
+    # Higher = fewer LLM calls but less responsive follow-ups
+    replan_batch_size: 5
+
+    # Significance threshold: Only call LLM if files changed exceeds this (default: 10)
+    # Changes below this threshold are considered "minor" and skip LLM analysis
+    replan_significance_threshold: 10
+
+    # Max frequency: Minimum minutes between replanning batches (default: 30)
+    # Prevents too-frequent LLM calls even if batch size reached
+    replan_max_frequency_minutes: 30
+
+    # ---------------------------------------------------------------------------
+    # Production Hardening (Phase 5)
+    # ---------------------------------------------------------------------------
+    # Error handling, timeouts, and fallback behavior for production deployments
+
+    # Fallback to legacy ticket generation if UDAR fails (default: true)
+    # When true, errors in UDAR automatically fall back to legacy mode
+    # When false, UDAR errors propagate to the caller
+    fallback_to_legacy: true
+
+    # Timeout for UDAR agent execution in seconds (default: 120 = 2 minutes)
+    # Prevents runaway LLM calls from blocking indefinitely
+    timeout_seconds: 120
+
+    # Enable cost tracking in AgentSession table (default: true)
+    # Tracks input/output tokens and estimated USD cost per goal
+    enable_cost_tracking: true
+
+    # Max retries on transient errors (default: 0 = no retry)
+    # For network errors, rate limits, etc. NOT for validation failures.
+    max_retries_on_error: 0