AI and Stage Contracts

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]

Loading

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

PR review context also contains a deterministic reviewScope: base SHA, optional completed checkpoint SHA, frozen target SHA, head repository, and file snapshot digest. With no checkpoint, changed-file context is the full PR diff. With a checkpoint, it is the checkpoint-to-target comparison. Human review context and open review threads remain available, while superseded GitVibe review bodies older than the checkpoint are omitted to avoid repeatedly sending the same automation output.

Stage Reference

Stage	Target	Prompt dir	Schema	Default tools	Next states
investigate	Issue	investigate	investigate.v1	read, grep, glob, diff, github-search, web-fetch, web-search, agent	ready-for-validation, ready-for-implementation, needs-info, blocked
validate	Issue or Discussion	validate	validate.v1	read, grep, glob, github-search, web-fetch, web-search, agent	Issue: ready-for-implementation, needs-info, blocked; Discussion: ready for materialization, needs-info, blocked
materialize	Discussion	materialize	materialize.v2	read, grep, glob	implementation-issues-ready, blocked
review-matrix	Pull request	review-matrix	review-matrix.v1	read, grep, glob, diff, agent	review-passed, changes-required, blocked

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

Loading

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

AI Adapters

Adapter	Execution	Auth source
codex-sdk	OpenAI Codex SDK with isolated temporary CODEX_HOME, proxy base URL, and JSON schema validation	base_url.from_bundle and api_key.from_bundle
claude-code-sdk	Claude Code SDK with installed config, schema output, no session persistence, and MCP config	Profile env mapping from bundle or literals

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]

Loading

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

review.yml matrix members use a separate checkout of the exact frozen PR head. Claude members receive an explicit read, grep, and glob tool set. Model MCP servers are disabled for review members; Codex members also run with a read-only sandbox, web search disabled, and network access disabled. The trusted base checkout continues to supply GitVibe configuration, profiles, roles, prompts, and action code. The finalizer receives member results and does not need repository tools.

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 is a schema-validated AI classifier, not a regex discovery pass. It 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. Large sources are packed into bounded classifier batches, and chunk overlap is preserved across batch boundaries so an instruction split at the edge of one classifier call still appears intact in the next call.

The classifier uses the same configured AI routing as the stage being protected: matrix member runs use that member profile, role-group finalization uses the synthesizer profile, and single-profile stages use their configured stage profile. 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.

For review.yml, the leading security job records a digest of the scanned input context. A member or finalizer reuses that attestation only when its reconstructed context has the same digest and frozen review snapshot. Changed timeline or file content causes the normal input gate to run again. This removes duplicate safety classifier calls without weakening the context boundary.

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 matching context. 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. Incremental output may also include resolved_finding_ids for prior GitVibe findings proven fixed in the frozen target tree. GitVibe rejects duplicate, unknown, or simultaneously current and resolved IDs 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. Review checkpoint selection is not a workflow input and cannot be forced by a consumer; GitVibe derives it from completed review result markers.