Code Evidence & Provenance
Relevant source files
The following files were used as context for generating this wiki page:
The Code Evidence & Provenance system in Orcy provides a structured framework for linking codebase artifacts—such as commits, pull requests, branches, and CI/CD runs—directly to tasks and missions. This system ensures that all work performed by agents or humans is backed by verifiable code-level evidence, creating a durable audit trail of what was changed and why.
The system is designed with an append-only philosophy, where evidence is never silently deleted but rather corrected or superseded. It supports diverse discovery paths, including webhook automated ingestion, commit trailer parsing (e.g., Orcy-Task keys), and explicit reporting via API or MCP tools.
Sources: CONTEXT.md:129-144, packages/shared/src/types/code-evidence.ts:251-253
System Architecture & Data Model
The system centers around the code_evidence_links table, which acts as a polymorphic join between Orcy work items (Tasks or Missions) and various code artifacts.
Entity Relationships
The following diagram illustrates the relationship between habitats, work items, and the various evidence primitives.
Core Components
| Component | Description |
|---|---|
| Evidence Link | A record connecting a target_id (Task/Mission) to a specific piece of evidence. |
| Evidence Gap | A lifecycle record for known missing evidence, explaining why a requirement isn't met. |
| Completeness Status | A derived roll-up (Complete, Partial, Missing, N/A) for a work item's evidence health. |
| Verification State | Tracks if an artifact is confirmed (Verified, Unverified, Stale, Failed). |
Sources: packages/shared/src/types/code-evidence.ts:1-50, CONTEXT.md:154-180
Evidence Ingestion & Linking
Orcy supports multiple ingestion sources, each assigned a baseline confidence score. Automated sources like webhooks have higher confidence (1.0) compared to agent-reported data (0.75).
Discovery Patterns
Evidence is discovered through several primary mechanisms:
- Webhooks: Automated ingestion from GitHub/GitLab.
- Commit Trailers: Parsing
Orcy-Task: <id>orOrcy-Mission: <id>from git commit messages. - Artifact Mirroring: Automatically converting Task artifacts into structured evidence links.
- Manual/Agent Reporting: Explicitly providing URLs or branch names via tools.
Sources: packages/shared/src/types/code-evidence.ts:168-180, packages/api/src/services/codeEvidenceService.ts:10-40
Link Creation Logic
When an evidence link is created, the system attempts to parse URLs into specific types using defined patterns:
Completeness & Lifecycle Management
Completeness is a calculated metric that determines if a task or mission has sufficient provenance.
Completeness State Machine
The status is derived based on the presence of active links and reported gaps.
| State | Condition |
|---|---|
| Complete | At least one active link; zero active gaps. |
| Partial | At least one active link AND at least one active gap. |
| Missing | Zero active links; at least one active gap. |
| Not Applicable | Explicit "Not Applicable" override has been set by a user. |
| Unknown | Zero links AND zero gaps reported. |
Sources: packages/api/src/services/codeEvidence/completeness.ts:77-100, packages/shared/src/types/code-evidence.ts:25-30
Correction and Supersession
Orcy uses an append-only model for evidence correction. If a link is incorrect, it is updated with a correction_reason and a reference to a replacement_link_id.
Implementation Details
Git Commit Trailer Keys
The system specifically looks for these trailers in commit messages to perform automatic linking:
Orcy-Task: Associates a commit with a Task ID.Orcy-Mission: Associates a commit with a Mission ID.
Sources: packages/shared/src/types/code-evidence.ts:182-185
Evidence Types Summary
| Type | Description |
|---|---|
branch | A git branch reference. |
pull_request | A GitHub PR or GitLab Merge Request. |
commit | A specific git commit SHA. |
changed_file | A record of a specific file change (path, additions, deletions). |
pipeline_run | A CI/CD workflow or job execution. |
review | A code review status (Approved, Changes Requested). |
Sources: packages/shared/src/types/code-evidence.ts:1-10
Conclusion
The Code Evidence & Provenance system provides the critical link between high-level orchestration and low-level code changes. By supporting polymorphic evidence types and maintaining a durable, corrected audit history, Orcy ensures that every task's completion is backed by verifiable artifacts, facilitating high-trust pod collaboration.
Sources: CONTEXT.md:129-144, packages/api/src/services/codeEvidenceService.ts:1-20