code-talk.yaml

# =============================================================================
# code-talk: Reusable workflow for AI-powered code exploration
# =============================================================================
#
# A battle-tested workflow for answering code questions across multiple
# repositories with architecture-aware routing.
#
# Usage:
#   imports:
#     - ./code-talk.yaml
#
#   checks:
#     code-help:
#       type: workflow
#       workflow: code-talk
#       args:
#         question: "How does authentication work?"
#         architecture: ./ARCHITECTURE.md
#         docs_repo: my-org/docs
#         projects:
#           - id: backend
#             repo: my-org/backend
#             description: Backend API services
#
# =============================================================================

id: code-talk
name: Code Talk
description: AI-powered code exploration across multiple repositories with confidence scoring
version: "1.0.0"

imports:
  - project-setup.yaml

inputs:
  - name: question
    required: true
    description: The code question to answer
    schema:
      type: string

  - name: architecture
    required: true
    description: |
      Architecture model - file path or inline markdown describing
      project topology and routing rules
    schema:
      type: string

  - name: docs_repo
    required: true
    description: Documentation repository (owner/name format)
    schema:
      type: string

  - name: projects
    required: true
    description: |
      Array of available code projects for AI routing:
        - id: unique identifier for routing
        - repo: GitHub repository (owner/name)
        - description: used by AI for routing decisions
    schema:
      type: array
      items:
        type: object
        properties:
          id: { type: string }
          repo: { type: string }
          description: { type: string }
          sandbox: { type: string }
          services:
            type: object
            additionalProperties:
              type: object
              properties:
                image: { type: string }
                ports:
                  type: array
                  items: { type: number }
                environment:
                  type: object
                  additionalProperties: { type: string }
                volumes:
                  type: array
                  items: { type: string }
                healthcheck:
                  type: object
                  properties:
                    test:
                      type: array
                      items: { type: string }
                    interval: { type: string }
                    timeout: { type: string }
                    retries: { type: number }
              required: [image]
          setup:
            type: array
            items: { type: string }
          knowledge: { type: string }
        required: [id, repo, description]

  - name: max_projects
    default: 3
    description: Maximum code projects to checkout (excludes docs)
    schema:
      type: number

  - name: docs_ref
    default: main
    description: Git ref for docs repository
    schema:
      type: string

  - name: routing_prompt
    required: false
    description: Additional routing instructions (appended to built-in)
    schema:
      type: string

  - name: exploration_prompt
    required: false
    description: Additional exploration instructions (appended to built-in)
    schema:
      type: string

  - name: ai_model
    required: false
    description: Override AI model for exploration step
    schema:
      type: string

outputs:
  - name: answer
    description: The answer object with text
    value_js: |
      const result = outputs?.['explore-code'];
      if (result?.answer) return result.answer;
      const resultText = typeof result?.text === 'string' ? result.text.trim() : '';
      if (resultText.length > 0) {
        return { text: resultText };
      }
      const routeNotes = outputs?.['setup-projects']?.routing_decision?.notes;
      const checkoutProjects = outputs?.['setup-projects']?.checkout_projects;
      if (
        (!Array.isArray(checkoutProjects) || checkoutProjects.length === 0) &&
        typeof routeNotes === 'string' &&
        routeNotes.trim().length > 0
      ) {
        return { text: routeNotes.trim() };
      }
      return { text: 'Code exploration did not produce an answer.' };

  - name: exploration_status
    description: Outcome of the exploration step
    value_js: |
      const result = outputs?.['explore-code'];
      if (result?.answer?.text) return 'success';
      const resultText = typeof result?.text === 'string' ? result.text.trim() : '';
      if (resultText.length > 0) {
        if (/timed out/i.test(resultText)) return 'timeout';
        return 'failed';
      }
      const routeNotes = outputs?.['setup-projects']?.routing_decision?.notes;
      const checkoutProjects = outputs?.['setup-projects']?.checkout_projects;
      if (
        (!Array.isArray(checkoutProjects) || checkoutProjects.length === 0) &&
        typeof routeNotes === 'string' &&
        routeNotes.trim().length > 0
      ) {
        return 'no_projects';
      }
      return 'failed';

  - name: exploration_error
    description: Timeout or failure detail when exploration did not return a real answer
    value_js: |
      const result = outputs?.['explore-code'];
      if (result?.answer?.text) return '';
      const resultText = typeof result?.text === 'string' ? result.text.trim() : '';
      if (resultText.length > 0) return resultText;
      const routeNotes = outputs?.['setup-projects']?.routing_decision?.notes;
      const checkoutProjects = outputs?.['setup-projects']?.checkout_projects;
      if (
        (!Array.isArray(checkoutProjects) || checkoutProjects.length === 0) &&
        typeof routeNotes === 'string' &&
        routeNotes.trim().length > 0
      ) {
        return routeNotes.trim();
      }
      return 'Code exploration did not produce an answer.';

  - name: references
    description: Code/doc references from exploration
    value_js: |
      const result = outputs?.['explore-code'];
      return result?.references ?? [];

  - name: confidence
    description: |
      Confidence in the final answer ("high", "medium", or "low").
      Treat non-high confidence as a signal to verify before acting.
    value_js: |
      const result = outputs?.['explore-code'];
      if (result?.confidence) return result.confidence;
      const routeNotes = outputs?.['setup-projects']?.routing_decision?.notes;
      if (typeof routeNotes === 'string' && routeNotes.trim().length > 0) return 'low';
      return 'low';

  - name: confidence_reason
    description: |
      Why confidence is not high. Should explain missing evidence,
      ambiguity, or investigation gaps. May be empty only when confidence is high.
    value_js: |
      const result = outputs?.['explore-code'];
      const confidence = result?.confidence;
      const reason = result?.confidence_reason;
      if (typeof reason === 'string' && reason.trim().length > 0) return reason;
      if (confidence === 'high') return '';
      const resultText = typeof result?.text === 'string' ? result.text.trim() : '';
      if (resultText.length > 0) return resultText;
      const routeNotes = outputs?.['setup-projects']?.routing_decision?.notes;
      const checkoutProjects = outputs?.['setup-projects']?.checkout_projects;
      if (
        (!Array.isArray(checkoutProjects) || checkoutProjects.length === 0) &&
        typeof routeNotes === 'string' &&
        routeNotes.trim().length > 0
      ) {
        return routeNotes.trim();
      }
      return 'Code exploration did not produce an answer.';

  - name: projects_explored
    description: Which project IDs were checked out
    value_js: |
      const checkoutProjects = outputs?.['setup-projects']?.checkout_projects;
      if (Array.isArray(checkoutProjects)) {
        return checkoutProjects
          .map(function (p) { return p?.project_id; })
          .filter(function (p) { return p; });
      }
      return [];

  - name: projects_explored_details
    description: Project details for routed projects (id, repo, description, reason)
    value_js: |
      const checkoutProjects = outputs?.['setup-projects']?.checkout_projects;
      if (!Array.isArray(checkoutProjects)) return [];

      const result = [];
      for (let i = 0; i < checkoutProjects.length; i++) {
        const p = checkoutProjects[i];
        if (!p?.project_id) continue;
        result.push({
          id: p.project_id,
          repo: p.repository ?? '',
          description: p.description ?? '',
          reason: p.reason ?? ''
        });
      }
      return result;

  - name: checkout_projects
    description: Checked-out project paths aligned with routed projects
    value_js: |
      return outputs?.['setup-projects']?.checkout_projects ?? [];

steps:
  # ===========================================================================
  # Step 1: Project routing and checkout (shared sub-workflow)
  # ===========================================================================
  setup-projects:
    type: workflow
    workflow: project-setup
    criticality: internal
    assume:
      - "true"
    args:
      question: "{{ inputs.question }}"
      architecture: "{{ inputs.architecture }}"
      docs_repo: "{{ inputs.docs_repo }}"
      projects:
        expression: "inputs.projects"
      max_projects:
        expression: "inputs.max_projects ?? 3"
      docs_ref: "{{ inputs.docs_ref }}"
      routing_prompt: "{{ inputs.routing_prompt }}"

  # ===========================================================================
  # Step 2: Explore code across all projects (main AI call)
  # ===========================================================================
  explore-code:
    type: ai
    criticality: internal
    depends_on: [setup-projects]
    fanout: reduce
    assume:
      - "outputs['setup-projects']?.checkout_projects?.length > 0"
    ai:
      # ── Timeout Configuration ──────────────────────────────────────────
      # Probe soft timeout: 25 min — observer fires here
      ai_timeout: 1500000
      # Negotiated: observer decides if exploration needs more time
      timeout_behavior: negotiated
      # Budget: 20 min total (2 × 10 min extensions)
      negotiated_timeout_budget: 1200000
      negotiated_timeout_max_requests: 2
      negotiated_timeout_max_per_request: 600000
      # No hard timeout needed; parent deadline propagation caps this step
      # ──────────────────────────────────────────────────────────────────
      skip_code_context: true
      enableDelegate: true
      enableTasks: true
      enableExecutePlan: false
      max_iterations: 100
      prompt_type: code-explorer
      allowBash: true
      bashConfig:
        allow:
          # Git read-only commands only (no commit, push, reset, rebase, merge, etc.)
          - "git:diff:*"
          - "git:log:*"
          - "git:show:*"
          - "git:blame:*"
          - "git:checkout:*"
          - "git:branch:*"
          - "git:tag:*"
          - "git:fetch:*"
          - "git:status:*"
          - "git:rev-parse:*"
          - "git:ls-files:*"
          - "git:ls-tree:*"
          - "git:worktree:list:*"
          - "git:worktree:remove:*"
          # File operations — ONLY ls and wc allowed
          # Do NOT use cat/grep/find/head/tail for code exploration —
          # use search() and extract() tools instead, they are faster and more accurate
          - "ls:*"
          - "wc:*"
          # GitHub CLI read-only operations
          - "gh:run:*"
          - "gh:run:list:*"
          - "gh:run:view:*"
          - "gh:run:watch:*"
          - "gh:workflow:*"
          - "gh:workflow:list:*"
          - "gh:workflow:view:*"
          - "gh:pr:*"
          - "gh:pr:list:*"
          - "gh:pr:view:*"
          - "gh:pr:checks:*"
          - "gh:pr:diff:*"
          - "gh:issue:*"
          - "gh:issue:list:*"
          - "gh:issue:view:*"
          - "gh:repo:view:*"
          - "gh:repo:list:*"
          - "gh:api:*"
          - "gh:release:list:*"
          - "gh:release:view:*"
          # Curl for API calls (read-only)
          - "curl:-s:*"
          - "curl:*"
        timeout: 60000
      completion_prompt: |
        VALIDATION STEP — Review your response for accuracy before finalizing.

        ╔══════════════════════════════════════════════════════════════╗
        ║  NEVER REDO COMPLETED WORK. Check search results above     ║
        ║  before taking any action. Only act on GENUINE gaps.       ║
        ╚══════════════════════════════════════════════════════════════╝

        Step 1 — Review completed work (MANDATORY):
        - Review ALL search/delegate results in the conversation above
        - What code was already found? What files were already explored?
        - Do NOT re-search for information that is already in the results above

        Step 2 — Check your response:
        1. Are code references accurate based on search results above?
        2. Did you verify claims independently, or just confirm the user's theory?
        3. Does your answer have unsupported assertions not backed by tool results?

        Step 3 — Act ONLY on genuine gaps:
        - If everything checks out: respond with your previous answer as-is
        - If your text has inaccuracies but evidence exists above: fix the text only
        - If you find a SPECIFIC unsupported factual claim with NO evidence above:
          ONLY THEN call delegate/search for that specific claim
        - NEVER re-search topics that already have results in the conversation

        Confidence calibration — be HONEST, not optimistic:
        - "high" ONLY with definitive code evidence that fully answers the question
        - "medium" when relevant code found but not all aspects verified
        - "low" when based on naming conventions, comments, or partial evidence
        - Do NOT default to "high" — inflated confidence wastes follow-up time
    schema:
      type: object
      additionalProperties: false
      properties:
        answer:
          type: object
          additionalProperties: false
          properties:
            text:
              type: string
              description: |
                The complete answer with explanations. MUST end with a
                "## References" section containing clickable GitHub links.
            summary:
              type: string
              description: One-line summary (optional)
          required: [text]
        references:
          type: array
          description: Code and documentation references (must not be empty)
          items:
            type: object
            properties:
              project:
                type: string
                description: Project ID (e.g., "tyk", "tyk-analytics")
              file:
                type: string
                description: File path relative to repo root
              lines:
                type: array
                description: Line numbers (start and end if range)
                items: { type: number }
              url:
                type: string
                description: Full GitHub URL with line numbers (e.g., https://github.com/org/repo/blob/main/file.go#L42-L50)
              snippet:
                type: string
                description: Brief description of what this reference shows
            required: [project, file, url]
        confidence:
          type: string
          enum: [high, medium, low]
          description: |
            Confidence in the answer based on evidence quality and investigation coverage.
            Use "high" only when claims are directly backed by code/doc evidence.
        confidence_reason:
          type: string
          description: |
            Why confidence is not high (required to be meaningful for medium/low confidence).
            Leave empty string only when confidence is high.
      required: [answer, references, confidence, confidence_reason]
    prompt: |
      <instructions>
      Bash tool rules:
      - Use search/extract tools for code exploration, NOT bash (no grep, cat, find)
      - Bash is ONLY for: git, gh CLI, curl, and system commands
      - Use the workingDirectory parameter instead of `cd`; no pipes or chained commands
      - Always use relative paths (e.g., "gateway/mw_jwt.go"), never absolute /tmp/ paths

      Branch switching:
      - Repos are shallow clones (fetch_depth: 1). Always fetch before checkout.
      - IMPORTANT: Never use `git checkout <branch-name>` — it fails when the branch
        is checked out in another worktree. Instead use detached HEAD:
          `git fetch origin <branch> && git checkout FETCH_HEAD`
      - For PRs: `git fetch origin pull/<N>/head && git checkout FETCH_HEAD`
      - For tags: `git fetch --tags` then `git checkout <tag>`
      - If the question mentions a specific branch (e.g. "on the feature-x branch"),
        switch to it FIRST before searching. Content may only exist on that branch.

      Delegate usage:

      Task protocol:
      - Before substantive work begins, create the task or tasks first.
      - This applies to long-running single-goal investigations too, not only multi-goal requests.
      - If there is a clear list of independent investigation jobs, create one task per job before starting.
      - When a task starts, mark it in_progress immediately.
      - When a task is actually done, complete it immediately before moving on.
      - Do not leave finished tasks pending or in_progress.
      - Prefer one active in_progress task at a time unless work is truly parallel.
      - Before the final answer, every created task must be completed or cancelled.

      - Each delegate should answer ONE specific question (not "look at the code")
      - Run multiple delegates in PARALLEL for different hypotheses or components
      - If you spawn delegates for independent jobs, create matching tasks first and keep them updated in real time
      - Ask delegates to return specific file paths and line numbers
      - Do NOT delegate or re-search the same question twice in one investigation
      - If a delegate returns enough evidence for the current claim, stop and use it
      - NEVER spawn a new delegate for the same topic as a previous delegate.
        If delegates 1-3 all searched for "session context metadata", do NOT spawn
        delegate 4 for "session context metadata" again. Use the results you have.
      - Before spawning a delegate, review results from ALL prior delegates.
        If the information is already available, use it instead of re-delegating.
      - If jobs are not truly independent, do not parallelize them. Keep work sequential and keep task state accurate.

      Relay complete data from tools — do not summarize or compress tool output.

      Investigation scope:
      - Stop once you have enough evidence to answer the question accurately
      - If this is an implementation handoff for engineer, optimize for the minimum
        sufficient handoff: repo, branch/ref, target files, relevant tests, and the
        key evidence explaining why those files matter
      - Prefer one search followed by targeted extract over repeated broad searches
      </instructions>

      {% if inputs.exploration_prompt %}
      <additional_instructions>
      {{ inputs.exploration_prompt }}
      </additional_instructions>
      {% endif %}

      <context>
        <question>
          {{ inputs.question }}
        </question>

        <architecture>
        {{ inputs.architecture }}
        </architecture>

        <routing_decision>
          {{ outputs['setup-projects'].routing_decision | json }}
        </routing_decision>

        <docs_checkout>
          <repo>{{ inputs.docs_repo }}</repo>
          <ref>{{ inputs.docs_ref }}</ref>
          <path>{{ outputs['setup-projects'].docs_path }}</path>
        </docs_checkout>

        {% assign projects = outputs['setup-projects'].checkout_projects %}
        <projects>
        {% if projects %}
        {% for p in projects %}
          <project>
            <id>{{ p.project_id }}</id>
            <repo>{{ p.repository }}</repo>
            <path>{{ p.path }}</path>
            <reason>{{ p.reason | default: 'not provided' }}</reason>
            {% if p.sandbox %}<sandbox>{{ p.sandbox }}</sandbox>{% endif %}
            {% if p.services %}<services>{{ p.services | json }}</services>{% endif %}
            {% if p.setup %}<setup>{{ p.setup | json }}</setup>{% endif %}
            {% if p.knowledge %}<knowledge>{{ p.knowledge }}</knowledge>{% endif %}
          </project>
        {% endfor %}
        {% endif %}
        </projects>
      </context>

      <task>
      For each project in <projects>, use search/extract tools to find the relevant
      implementation, then consult docs to confirm semantics. When multiple projects
      are involved, trace data and config flow across them.

      Efficiency rules for this investigation:
      - Reuse evidence already found in earlier tool results
      - If the question is narrow and the relevant files are already identified,
        stop exploring and answer
      - If the next consumer is engineer, avoid broad code archaeology once the
        implementation target and validation path are clear

      Synthesize a single answer:
      - Ground everything in code/docs evidence
      - End with a "## References" section with clickable GitHub links:
        - [file.go:42-50](https://github.com/org/repo/blob/main/path/file.go#L42-L50) - description

      Return in schema format: answer.text, answer.summary (optional), references array,
      confidence (high/medium/low), confidence_reason (explain what's missing if not high).
      </task>

# =============================================================================
# Tests
# =============================================================================
tests:
  defaults:
    strict: true
    ai_provider: mock

  cases:
    - name: basic-code-question
      event: manual
      fixture: local.minimal
      workflow_input:
        question: "How does authentication work?"
        architecture: |
          # Architecture
          ## Projects
          - gateway: API Gateway
          - backend: Backend services
        docs_repo: org/docs
        projects:
          - id: gateway
            repo: org/gateway
            description: API Gateway
          - id: backend
            repo: org/backend
            description: Backend services
      mocks:
        setup-projects:
          docs_path: "/tmp/visor/docs"
          routing_decision:
            projects:
              - project_id: "gateway"
                reason: "Gateway handles authentication"
          project_items:
            - project_id: "gateway"
              repository: "org/gateway"
              description: "API Gateway"
              reason: "Gateway handles authentication"
          checkout_projects:
            - project_id: "gateway"
              repository: "org/gateway"
              description: "API Gateway"
              path: "/tmp/visor/project"
              reason: "Gateway handles authentication"
              sandbox: null
              services: null
              setup: null
              knowledge: null
        explore-code:
          answer:
            text: "Authentication is handled in the gateway via JWT middleware."
            summary: "JWT auth in gateway"
          references:
            - project: gateway
              file: src/auth/jwt.go
              url: https://github.com/org/gateway/blob/main/src/auth/jwt.go#L42
          confidence: high
          confidence_reason: ""
      expect:
        calls:
          - step: setup-projects
            exactly: 1
          - step: explore-code
            exactly: 1
        workflow_output:
          - path: answer.text
            equals: "Authentication is handled in the gateway via JWT middleware."
          - path: confidence
            equals: "high"

    - name: multi-project-question
      event: manual
      fixture: local.minimal
      workflow_input:
        question: "How does data flow from gateway to backend?"
        architecture: "# Arch"
        docs_repo: org/docs
        projects:
          - id: gateway
            repo: org/gateway
            description: API Gateway
          - id: backend
            repo: org/backend
            description: Backend services
      mocks:
        setup-projects:
          docs_path: "/tmp/visor/docs"
          routing_decision:
            projects:
              - project_id: "gateway"
                reason: "Handles incoming requests"
              - project_id: "backend"
                reason: "Processes data"
          checkout_projects:
            - project_id: "gateway"
              repository: "org/gateway"
              description: "API Gateway"
              path: "/tmp/visor/project-1"
              reason: "Handles incoming requests"
              sandbox: null
              services: null
              setup: null
              knowledge: null
            - project_id: "backend"
              repository: "org/backend"
              description: "Backend services"
              path: "/tmp/visor/project-2"
              reason: "Processes data"
              sandbox: null
              services: null
              setup: null
              knowledge: null
        explore-code:
          answer:
            text: "Data flows via gRPC from gateway to backend."
          references: []
          confidence: medium
          confidence_reason: "References are incomplete for full cross-project verification."
      expect:
        calls:
          - step: setup-projects
            exactly: 1
          - step: explore-code
            exactly: 1

    - name: empty-routing-returns-notes
      strict: false
      event: manual
      fixture: local.minimal
      workflow_input:
        question: "Vague question"
        architecture: "# Arch"
        docs_repo: org/docs
        projects:
          - id: main
            repo: org/main
            description: Main app
      mocks:
        setup-projects:
          docs_path: "/tmp/visor/docs"
          routing_decision:
            projects: []
            notes: "I need more context to route this question."
          checkout_projects: []
      expect:
        calls:
          - step: setup-projects
            exactly: 1
        workflow_output:
          - path: answer.text
            equals: "I need more context to route this question."

    # =========================================================================
    # Edge Case: Checkout failure stops downstream checks
    # When setup-projects fails, explore-code doesn't run.
    # =========================================================================
    - name: checkout-failure-stops-exploration
      strict: false
      event: manual
      fixture: local.minimal
      workflow_input:
        question: "How does auth work?"
        architecture: "# Arch"
        docs_repo: org/docs
        projects:
          - id: backend
            repo: org/backend
            description: Backend services
      mocks:
        setup-projects:
          success: false
          error: "Repository not found: org/backend"
      expect:
        calls:
          - step: setup-projects
            exactly: 1
          # explore-code does NOT run because setup failed
          - step: explore-code
            exactly: 0

    # =========================================================================
    # Edge Case: Malformed AI response (missing required fields)
    # =========================================================================
    - name: malformed-routing-response
      strict: false
      event: manual
      fixture: local.minimal
      workflow_input:
        question: "What is X?"
        architecture: "# Arch"
        docs_repo: org/docs
        projects:
          - id: app
            repo: org/app
            description: Main app
      mocks:
        setup-projects:
          docs_path: "/tmp/visor/docs"
          routing_decision:
            notes: "I couldn't determine the projects"
          checkout_projects: []
      expect:
        calls:
          - step: setup-projects
            exactly: 1

    # =========================================================================
    # Edge Case: Unknown project ID in routing (not in input projects)
    # The project-setup filters out unknown IDs and only processes valid ones.
    # =========================================================================
    - name: unknown-project-id-filtered
      event: manual
      fixture: local.minimal
      workflow_input:
        question: "How does caching work?"
        architecture: "# Arch"
        docs_repo: org/docs
        projects:
          - id: backend
            repo: org/backend
            description: Backend services
      mocks:
        setup-projects:
          docs_path: "/tmp/visor/docs"
          routing_decision:
            projects:
              - project_id: "nonexistent-service"
                reason: "This doesn't exist"
              - project_id: "backend"
                reason: "Caching logic"
          checkout_projects:
            - project_id: "backend"
              repository: "org/backend"
              description: "Backend services"
              path: "/tmp/visor/project"
              reason: "Caching logic"
              sandbox: null
              services: null
              setup: null
              knowledge: null
        explore-code:
          answer:
            text: "Caching is implemented in the backend."
          references: []
          confidence: medium
          confidence_reason: "One routed project was invalid and filtered before exploration."
      expect:
        calls:
          - step: setup-projects
            exactly: 1
          - step: explore-code
            exactly: 1
        workflow_output:
          - path: answer.text
            equals: "Caching is implemented in the backend."

    # =========================================================================
    # Edge Case: max_projects limit respected
    # =========================================================================
    - name: max-projects-limit
      event: manual
      fixture: local.minimal
      workflow_input:
        question: "How does the full stack work?"
        architecture: "# Arch"
        docs_repo: org/docs
        max_projects: 2
        projects:
          - id: frontend
            repo: org/frontend
            description: Frontend app
          - id: backend
            repo: org/backend
            description: Backend services
          - id: database
            repo: org/database
            description: Database layer
          - id: cache
            repo: org/cache
            description: Cache layer
      mocks:
        setup-projects:
          docs_path: "/tmp/visor/docs"
          routing_decision:
            projects:
              - project_id: "frontend"
              - project_id: "backend"
              - project_id: "database"
              - project_id: "cache"
          checkout_projects:
            - project_id: "frontend"
              repository: "org/frontend"
              description: "Frontend app"
              path: "/tmp/visor/project-1"
              sandbox: null
              services: null
              setup: null
              knowledge: null
            - project_id: "backend"
              repository: "org/backend"
              description: "Backend services"
              path: "/tmp/visor/project-2"
              sandbox: null
              services: null
              setup: null
              knowledge: null
        explore-code:
          answer:
            text: "The stack flows from frontend through backend."
          references: []
          confidence: medium
          confidence_reason: "Exploration scope was reduced by max_projects limit."
      expect:
        calls:
          - step: setup-projects
            exactly: 1
          - step: explore-code
            exactly: 1

    # =========================================================================
    # Project-level services, setup, and sandbox fields
    # Verifies new project config fields flow through setup-projects
    # =========================================================================
    - name: project-services-and-setup
      event: manual
      fixture: local.minimal
      workflow_input:
        question: "How do integration tests work in tyk?"
        architecture: "# Arch"
        docs_repo: org/docs
        projects:
          - id: tyk
            repo: TykTechnologies/tyk
            description: Tyk Gateway
            sandbox: go-env
            services:
              redis:
                image: redis:7-alpine
              mongo:
                image: mongo:6
                environment:
                  MONGO_INITDB_DATABASE: tyk
            setup:
              - make deps
              - go generate ./...
            knowledge: "docs/internal/testing.md"
          - id: tyk-pump
            repo: TykTechnologies/tyk-pump
            description: Tyk Pump
      mocks:
        setup-projects:
          docs_path: "/tmp/visor/docs"
          routing_decision:
            projects:
              - project_id: "tyk"
                reason: "Integration tests are in the gateway"
          checkout_projects:
            - project_id: "tyk"
              repository: "TykTechnologies/tyk"
              description: "Tyk Gateway"
              path: "/tmp/visor/project"
              sandbox: "go-env"
              services:
                redis:
                  image: "redis:7-alpine"
                mongo:
                  image: "mongo:6"
                  environment:
                    MONGO_INITDB_DATABASE: "tyk"
              setup:
                - "make deps"
                - "go generate ./..."
              knowledge: "docs/internal/testing.md"
        explore-code:
          answer:
            text: "Integration tests use redis and mongo fixtures."
            summary: "Test infra in tyk"
          references:
            - project: tyk
              file: tests/integration_test.go
              url: https://github.com/TykTechnologies/tyk/blob/main/tests/integration_test.go
          confidence: high
          confidence_reason: ""
      expect:
        calls:
          - step: setup-projects
            exactly: 1
          - step: explore-code
            exactly: 1
        prompts:
          - step: explore-code
            contains:
              - "<sandbox>go-env</sandbox>"
              - "redis"
              - "mongo"
              - "make deps"
              - "testing.md"
        workflow_output:
          - path: answer.text
            equals: "Integration tests use redis and mongo fixtures."

    # =========================================================================
    # Project without services/setup (backwards compat)
    # Verifies projects without new fields still produce null values
    # =========================================================================
    - name: project-without-services
      event: manual
      fixture: local.minimal
      workflow_input:
        question: "What does the pump do?"
        architecture: "# Arch"
        docs_repo: org/docs
        projects:
          - id: pump
            repo: org/pump
            description: Tyk Pump
      mocks:
        setup-projects:
          docs_path: "/tmp/visor/docs"
          routing_decision:
            projects:
              - project_id: "pump"
                reason: "Direct match"
          checkout_projects:
            - project_id: "pump"
              repository: "org/pump"
              description: "Tyk Pump"
              path: "/tmp/visor/project"
              sandbox: null
              services: null
              setup: null
              knowledge: null
        explore-code:
          answer:
            text: "Pump aggregates analytics."
          references: []
          confidence: high
          confidence_reason: ""
      expect:
        calls:
          - step: setup-projects
            exactly: 1
          - step: explore-code
            exactly: 1

    # =========================================================================
    # Edge Case: Empty explore-code response handled gracefully
    # =========================================================================
    - name: empty-exploration-response
      event: manual
      fixture: local.minimal
      workflow_input:
        question: "What is feature X?"
        architecture: "# Arch"
        docs_repo: org/docs
        projects:
          - id: main
            repo: org/main
            description: Main app
      mocks:
        setup-projects:
          docs_path: "/tmp/visor/docs"
          routing_decision:
            projects:
              - project_id: "main"
          checkout_projects:
            - project_id: "main"
              repository: "org/main"
              description: "Main app"
              path: "/tmp/visor/project"
              sandbox: null
              services: null
              setup: null
              knowledge: null
        explore-code:
          # Minimal valid response with empty text
          answer:
            text: ""
          references: []
          confidence: low
          confidence_reason: "The final answer text is empty."
      expect:
        calls:
          - step: setup-projects
            exactly: 1
          - step: explore-code
            exactly: 1
        workflow_output:
          - path: answer.text
            equals: ""