How Veripsa Core works

Short answers, jump to the section. The page below has the full detail.

• Will it understand my repo? — see the canonical language and file-type matrix in the public integration contract.
• How does the check look on my PR? — the four advisory verdicts (Clear, Heads up, Wait in line, Unknown).
• Does it block my merges? — interaction with GitHub branch protection on each plan.
• How do I install? — install the hosted GitHub App, no CI changes needed.
• Optional guidance for merge-capable agents — Core already posts automatically; add guidance only if it fits your merge automation.
• Wait in line — what do I do? — read the snapshot; an optional veripsa-ack label can record a deliberate override.
• What does Unknown mean? — an honest “don't know” with the usual reasons.

Install Veripsa Core from GitHub. It runs as a hosted GitHub App, so there's no agent runtime setup and nothing to add to your CI. Checks and comments appear automatically. If coding agents already participate in merge decisions, the optional agent guidance can help them interpret the advisory consistently; Core does not depend on it.

New to Veripsa Core? The getting-started guide shows the PR check, how to respond to Wait in line, and the branch-protection option.

During install you pick which repositories Veripsa Core can access. It coordinates pull requests within each repository — it does not coordinate across separate repositories. You can change which repositories are covered, or uninstall, at any time from GitHub.

Open pull requests as you normally would. Veripsa Core posts a check on each PR and updates it as other PRs open, change, and merge. It uses only the minimal operational metadata needed to run the advisory. Source file bodies are not stored, displayed, or used for code review.

The check reports one of four states. They are advisory: they tell you what Veripsa Core observed, not what you must do.

• Clear. No collision was found with the other open pull requests Veripsa Core can see.
• Heads up. This PR may clash with another open PR, and part of it may need rework before it lands cleanly.
• Wait in line. Likely overlap was found, so this PR may need to wait behind related work. It is a suggestion, never a hard block.
• Unknown. Veripsa Core can't tell. Common reasons include changes outside the supported coverage envelope or repository context that is still becoming available. Unknown is an honest “don't know,” not a guarantee that there's no collision.

A material collision — a Wait in line, or a Heads up that names an in-flight partner PR — posts the check title Veripsa — Paused (acknowledge to proceed) and uses GitHub's action_required conclusion. Veripsa itself adds no routine acknowledgement step: the conclusion gates a merge only if your repository makes the Veripsa check required. If a human has reviewed the specific overlap and your team wants an auditable exception that moves this check to neutral, add the veripsa-ack label to the pull request. The label means “I have seen this snapshot of the collision and chosen to land” — it is an acknowledgement, not an approval. If the overlapping work changes afterward, Veripsa Core can surface the contention again.

The canonical language, framework, and structural-surface coverage matrix lives in the public integration contract. Representative coverage includes Python, TypeScript, JavaScript, Go, Java, and Rust; Astro, Vue, and Svelte; CSS, Sass, Less, and Stylus; and schema, API, IaC, and configuration files, with the public matrix as the canonical complete list. If work is outside the current envelope, the check may return an honest Unknown rather than guess. Source file bodies may be read transiently to derive the documented metadata; they are not retained or displayed.

Open the canonical language and file-type matrix.

Out of scope: generated artefacts, binary assets, vendored bundles, and files outside the current coverage envelope. A pull request that only touches out-of-scope files may return Unknown; this is deliberate, not a bug.

Unknown is an intentional state — Veripsa Core would rather say “I can't tell” than imply a verdict it can't back up. You will see it for changes that fall outside what Veripsa can confidently classify. Typical triggers:

• The PR is mostly outside the supported coverage envelope.
• The PR touches files where Veripsa Core cannot extract useful structure.
• The repository or branch context is still becoming available after install or major repository changes.
• The safe answer is to ask for human review instead of guessing.

What to do about it: usually nothing. Unknown means “not analyzed, not safe” — review the PR as you normally would. If Unknown appears repeatedly on work you expected Veripsa Core to understand, contact support with the repository name and PR URL.

Veripsa Core coordinates pull requests within each repository. A monorepo is supported when the changed files are in covered areas; open PRs in the repo can be considered together regardless of subdirectory.

Veripsa Core does not coordinate across repositories today, even when they are owned by the same GitHub account. A PR in repo A and a PR in repo B will not warn each other about overlapping changes, even if the work belongs to the same product area. Cross-repository coordination is on the roadmap and is not a current claim.

Veripsa Core is always advisory — it posts a check whose state you can read on the pull request page on every GitHub plan, including Free. Turning that check into a gate (i.e. one of the required checks that must pass before merge) requires GitHub branch protection, which has different availability on private repositories depending on plan.

Whether to mark Veripsa Core required is your call — see Operational best-practices below. The check is useful as an advisory signal whether or not it gates the merge.

Veripsa Core aims for precise silence — the goal is that when it warns, it's worth reading. A few broad patterns can still produce warnings that deserve human triage:

• Broad shared surfaces. Some repository-wide files or shared project areas can make independent work look more related than it is. If the two PRs are genuinely independent, continue through your normal advisory merge process. No routine acknowledgement is required; a team may use the optional ACK label to record a deliberate exception to a material warning.
• Brand-new files only. If both PRs add files that don't exist on main yet, Veripsa Core may report Unknown rather than Clear for those paths until one side lands and main absorbs them. That's honest, not a bug — there's nothing to compare to yet.
• Optional ACK label. The veripsa-ack label means “I have seen this snapshot of the warning and chosen to land”. A material warning is posted as action_required; adding the label records the reviewed exception and moves that check to neutral. It is not an approval, review sign-off, or claim that the collision is resolved. If the overlapping work changes, the ACK is no longer current and Veripsa Core can return the material warning.
• Cross-account or transferred repositories. If a repo is transferred across GitHub accounts, history that lived under the previous owner is not carried forward (privacy boundary). Veripsa Core re-ingests from the new owner's view of main.

Veripsa Core uses only the GitHub App permissions and events needed to run advisory checks. Events are processed with minimal content-free repository and pull-request metadata. Source file bodies may be read transiently to derive that metadata; they are not retained or displayed.

Veripsa Core is GitHub App first and free while in early access. GitHub Marketplace is the listing and future billing path. Legacy direct billing is not part of the active product flow, and there is no checkout step in the current install path.

Veripsa Core is designed to slot in alongside whatever review process you already run — including a merge queue (see Using Veripsa Core alongside your merge queue). Core needs no per-agent setup. If merge-capable agents are already part of your workflow, you can optionally add lightweight guidance — see Using Veripsa with Codex, Copilot, and Claude-style agents. A short setup checklist:

• Start advisory. Install on a repo you maintain, leave the check unrequired, and review several verdicts before you let it gate a merge.
• Make it required only after review.After reviewing enough verdicts on your own repository, you can add Veripsa Core to the required-check list in branch protection (GitHub's own plan must allow branch protection on private repos — GitHub Pro or higher; it's free on public repos). The optional veripsa-ack label can record an auditable override when you choose to land despite a Wait in line.
• Read the four verdicts at face value. Clear = nothing in flight overlaps. Heads up = look before you land. Wait in line = likely overlap was found; prefer waiting or use your normal advisory merge process. Unknown = not analyzed, not safe — review as you normally would.
• Read the percentage as plan coverage-ceiling usage. The dashboard reports how much of the current plan's coverage ceiling is in use. Its denominator is the plan ceiling, not the repository.
• Linked installations remain separate scopes. When more than one scope is linked, the dashboard shows the scope needing the most attention: over the ceiling first, then near the ceiling, then the highest utilization. Counts are never pooled into a synthetic organization-wide percentage.

Veripsa Core is advisory and never hard-blocks a merge by itself. Whether its check can block a merge is entirely up to you: your GitHub branch-protection rules decide what gates a merge. By default Veripsa Core informs your decision — it doesn't make it for you.

You can uninstall Veripsa Core at any time from your GitHub settings. Uninstalling stops processing and purges the rebuildable content-free working set for your GitHub installation. It is not the same as an account-erasure request: retained advisory history and lifecycle records are deleted through a separate erasure process. See the Privacy Policy for details.

Reference material lives in public repositories under the GetVeripsa GitHub organization, so you can read it without an account. These are intentionally separate from the Core engine repo, which stays private.

• veripsa-webhook-spec — the observable GitHub event, output, ACK, and data-handling contract. It intentionally excludes the private decision engine.
• ai-pr-collision-lab — a maintained toy repository for seeing the check on two prepared pull requests.