AI And Stage Contracts

GitVibe treats AI as stage-specific workers behind stable contracts. The app and runner own permissions, state transitions, validation, and deterministic writes.

Context Assembly

flowchart TD
  A[Issue, Discussion, or PR body] --> C[Conversation timeline]
  B[Comments, replies, reviews, review comments] --> C
  C --> D[Sort by creation time]
  D --> E[Attach parent and source references]
  E --> F[Add author association and repository permission metadata]
  F --> G[Render stage prompt]
  G --> H[Run selected AI adapter]
  H --> I[Validate JSON Schema output]
  I --> J[Deterministic GitHub writes]

Context includes the target artifact, timeline items, source comment metadata, handoffs from earlier stages, repository context, and prompt additions when configured.

Stage Reference

Stage routing is configured in Stage Routing. Read-only stages investigate, validate, and review-matrix may run as role-group matrix jobs before a finalizer synthesizes one schema result.

Current GitVibe stages do not write repository code, create branches, open pull requests, or remediate PR feedback. They investigate, validate, materialize implementation issue drafts, and review existing pull requests.

Stage Execution

sequenceDiagram
  participant Runner
  participant GitHub
  participant AI
  participant Validator

  Runner->>GitHub: Load issue, discussion, or PR context
  Runner->>GitHub: Publish transient running comment
  Runner->>Runner: Prepare stage plan and context files
  Runner->>AI: Send rendered system and user prompt
  AI->>Validator: Call output_validator or return structured output
  Validator->>Runner: Schema-valid JSON
  Runner->>GitHub: Apply deterministic writes
  Runner->>GitHub: Publish result comment and labels

AI output is never treated as direct authority. GitVibe validates the output first, then deterministic code decides what to write.

AI Adapters

Adapter profile examples live in AI Profiles.

Tool Policy

flowchart LR
  ReadOnly[Read-only stages] --> ReadTools[read, grep, glob, diff, web tools]
  Review[Review stages] --> ReviewTools[read, grep, glob, diff, agent]

Stage configs may restrict tools to a subset of the allowed default tools. They cannot add tools outside the stage definition.

Prompt Injection And Accepted Risk

GitVibe treats issue bodies, discussion replies, comments, pull request patches, repository files, handoffs, web content, MCP output, and future OCR text as untrusted. They may provide evidence, but they cannot override GitVibe system prompts, schemas, stage contracts, approval rules, validation, tool policy, or GitHub write boundaries.

The safety gate scans normalized content units rather than a shortened prompt string. Issue bodies, discussion replies, source comments, handoffs, PR review threads, and pull request changed-file patches are split into overlapping chunks for detection. Prompt rendering is separate: runner stages persist exact GitHub context into local files and send github_context.context_manifest plus github_context.context_files references to the SDK agent. The agent uses read or grep tools against those files when exact evidence is material, instead of receiving large inline prompt payloads.

High-risk input includes:

• instruction overrides that ask the model to ignore or replace GitVibe rules;
• encoded payloads that decode to stage, tool, validation, or approval control;
• suffix attacks that try to bypass branch, token, safety, or write rules;
• risky pull request patch text before review;
• suspicious downloadable links, attachment text, or fetched web content;
• requests to reveal secrets, provider keys, tokens, hidden prompts, or runner credentials.

When the gate blocks, GitVibe posts a schema-valid blocked result, applies gvi:blocked, and removes stale git-vibe:approved by default. A maintainer can change the flagged content, adjust safety configuration, handle the case manually, or apply git-vibe:accept-risk for one run. Accepted risk is run-bound and, for pull requests, head-SHA-bound. Security review then scans only post-cutoff delta context before downstream jobs may run.

Accepted risk does not make the review-matrix synthesizer responsible for old security findings. Once security review passes, finalization skips already accepted context for its pre-synthesis gate, filters the accepted-risk metadata source out of prompt context, and still scans finalizer-local inputs such as role definitions, MCP prompt additions, and new post-cutoff content.

Web Access Policy

GitVibe injects web safety rules into every AI stage system prompt. Web access is read-only research: agents must not submit forms, sign in, purchase, vote, post, comment, upload, or trigger state-changing website requests. Agents are also instructed not to download or execute suspicious files, installers, archives, binaries, scripts, or attachments.

github-search remains the deterministic tool for current-repository GitHub material. web-fetch and web-search are available only to stages that declare them, but web-search still requires an external search backend before it can return general internet results.

Legacy ai.security.web.allowed_domains config is accepted as a no-op for compatibility. It no longer gates web-fetch, web-search, or runtime-native web tools from AI runtimes. Prompt guidance is not a network boundary; use runner or network egress controls when a repository needs strict web isolation.

Structured Output

All stage schemas require:

{
  "stage": "investigate",
  "status": "completed",
  "summary": "...",
  "comment_body": "...",
  "next_state": "ready-for-implementation",
  "references": []
}

The exact required fields differ by stage. Schema files live in:

schemas/stages/

review-matrix.v1 may include inline_comments for blocking findings that can be anchored to exact pull request diff lines. Each item must include path, line, and body; start_line, side, severity, and finding_id are optional. finding_id is a stable review finding key and must match ^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$ when supplied. GitVibe rejects duplicate resolved finding IDs in one review result because reconciliation uses that key to match current findings to prior GitVibe review threads.

When an existing GitVibe inline review comment has a hidden git-vibe:review-finding id=... marker and the same issue still applies, the review output should reuse that id in inline_comments[].finding_id. Do not copy hidden markers into the visible body; GitVibe writes and strips those markers itself.

The runner writes result JSON files under RUNNER_TEMP when available, falling back to the repository working directory outside Actions. Reusable workflows upload those result files as artifacts. Examples:

git-vibe-investigate-result.json
git-vibe-review-matrix-result.json

Validation Commands

tests.commands remains repository configuration for handoff quality. Current GitVibe workflows do not run those commands automatically because code-writing and repair stages are removed. Configure them in Tests Commands so investigations can tell human implementers which checks matter.

Context Files And Budgets

GitVibe does not compact or summarize large GitHub context before the model runs. Runner stages create a unique per-run directory under RUNNER_TEMP when available, or the operating system temp directory outside Actions, then write the full context JSON, a manifest, and per-unit text files there. The prompt contains file paths, hashes, and metadata; the SDK agent reads the files it needs. Workflow timeouts and turn budgets are passed through workflow inputs and are summarized in Workflow Reference.