Common practices

VOUCHA works best as a maintainer-facing policy system. The strongest rollouts are explicit about what is trusted, what is merely suspicious, and what should still go to human review.

Recipes: turn an allowlist into a quiz fallback

Many repositories start with a hard rule such as “only existing contributors” or “only vouched authors.” VOUCHA can keep that trusted path while giving other contributors a way to confirm that a PR was intentional and that they stand behind the specific change.

The recipes below are starter .github/voucha.yml policies. They deliberately set min_changed_lines: 0, skip_paths: [], and require_approval: never so a ready-for-review human PR that does not match the named trust rule reaches the quiz immediately. Drafts and bots still follow their separate defaults. If you combine a recipe with an existing policy, remember that exemptions are ORed: remove any exemption that should no longer bypass the quiz.

Existing contributors skip; newcomers take the quiz

This is the quiz-backed version of “contributions from known contributors only.” Owners, members, collaborators, and authors GitHub identifies as prior contributors skip. Other human authors get a four-question challenge instead of an automatic rejection.

gates:
  - type: multiple_choice
    questions: 4
    pass_threshold: 3

trust:
  default_author_associations: [OWNER, MEMBER, COLLABORATOR]

exemptions:
  - type: author_association
    associations: [CONTRIBUTOR]

require_approval: never
min_changed_lines: 0
skip_paths: []

When “established contributor” means a repository-specific amount of merged work, replace the author_association exemption with:

exemptions:
  - type: prior_merged_prs
    min_count: 3

Vouched authors skip; everyone else takes the quiz

Use Vouch as the only durable author-trust list. Vouched authors skip, unknown authors take the quiz, and denounced authors receive a failed check. This strict version also quizzes owners and maintainers unless they are in the Vouch file; restore the default author associations if that is not desired.

gates:
  - type: multiple_choice
    questions: 4
    pass_threshold: 3

trust:
  default_author_associations: []
  vouch:
    enabled: true
    file: .github/VOUCHED.td

exemptions: []
require_approval: never
min_changed_lines: 0
skip_paths: []

A trusted team skips; everyone else takes the quiz

Use this instead of restricting contributions to an organization team. Active members of the configured team skip; everyone else has the quiz path. GitHub team checks require Members read permission on the GitHub App.

gates:
  - type: multiple_choice
    questions: 4
    pass_threshold: 3

trust:
  default_author_associations: []

exemptions:
  - type: github_team
    teams: [maintainers]
    roles: [member, maintainer]

require_approval: never
min_changed_lines: 0
skip_paths: []

Approved issue work skips; unsolicited work takes the quiz

This keeps an ordinary issue-triage fast path. A PR can skip when it matches a linked issue that carries verified maintainer approval through authorship, a trusted label, or assignment of the PR author. A missing, weak, or unapproved issue match falls through to the quiz.

gates:
  - type: multiple_choice
    questions: 4
    pass_threshold: 3

exemptions:
  - type: linked_issue_match
    require_same_repo: true
    require_trusted_signal: true
    min_match_score: 0.7
    trusted_labels: [accepted, ready]

require_approval: never
min_changed_lines: 0
skip_paths: []

This recipe needs the configured LLM for semantic issue-to-PR matching. If the signal cannot be verified, VOUCHA fails closed to the quiz rather than granting the exemption.

Everyone takes a quiz; sensitive files demand stronger proof

Use a normal quiz across the repository, then require a perfect longer quiz, maintainer approval, and fewer attempts for auth, deployment, migrations, or other high-risk paths. The first matching path rule wins.

gates:
  - type: multiple_choice
    questions: 4
    pass_threshold: 3

path_rules:
  - paths:
      - "src/auth/**"
      - "migrations/**"
      - ".github/workflows/**"
    gates:
      - type: multiple_choice
        questions: 6
        pass_threshold: 6
    require_approval: always
    max_attempts: 2
    cooldown_minutes: 30
    min_changed_lines: 0
    skip_paths: []

trust:
  default_author_associations: []

exemptions: []
require_approval: never
min_changed_lines: 0
skip_paths: []

Path rules change the policy for authors who reach the gate; they do not undo global trust exemptions. The strict recipe therefore removes author exemptions. If maintainers or teams are added back as exemptions, they will skip both the normal and sensitive-path quizzes.

Document accountability, not AI purity

Low-effort PRs are expensive because maintainers have to infer intent, check whether the author can iterate, and separate plausible-looking output from maintained work. Do not frame policy as “no AI.” Frame it as responsibility: AI assistance in authoring is allowed, but challenge answers must come from the author’s own understanding. The submitter must understand, test, explain, and support the change.

Use templates/contributing-policy.md as a starting point for CONTRIBUTING.md and templates/pull_request_template.md as a PR template. VOUCHA should reinforce that policy with an attestation challenge, not replace ordinary maintainer judgment.

If the repository wants the PR template fields to be mandatory, enable the accountability preflight:

accountability:
  require_pr_acknowledgement: true
  require_ai_disclosure: true

That check is deliberately about responsibility, not authorship detection.

Choose passkeys or maintainer-only confirmation

Passkeys are an optional confirmation path, not a requirement for completing a challenge. With the default policy, VOUCHA offers enrollment only after a clean pass and accepts only an already-established credential when a later correct result needs additional confirmation:

confirmation:
  webauthn: true

Contributors can decline enrollment, use a browser without WebAuthn, or lose access to a credential. In every case, a write-capable maintainer other than the PR author can comment /voucha confirm.

Repositories that do not want VOUCHA to store credential public keys can use the maintainer path exclusively:

confirmation:
  webauthn: false

This hides enrollment, removes passkey actions from pending confirmation, and rejects the registration and authentication endpoints for challenges created under that policy. It does not delete credentials that already exist. The setting is repository-wide and comes from the merge-target policy snapshot; it is not a path_rules override.

Pair with GitHub-native volume controls

For high-volume repositories, use GitHub’s PR creation limits, trusted bypass lists, or temporary restrictions on who can open pull requests to reduce review load before a PR reaches VOUCHA. VOUCHA is best at proving understanding and preserving review evidence for PRs that are already in the queue; GitHub should own raw volume throttling.

Trust contributors in tiers

Use author_login for named people, github_team for org-managed groups, repository_permission for repository roles, and prior_merged_prs when a repo wants to trust contributors after a visible body of merged work.

exemptions:
  - type: github_team
    teams: [maintainers, security]
  - type: prior_merged_prs
    min_count: 3

Team checks require Members read permission on the GitHub App. Merged-PR counts use GitHub search. If either signal is unavailable, VOUCHA falls back to the normal gate.

Keep individual passive signals report-only

Use passive signals to decide where maintainers should look harder, not to silently fail a PR. Form honeypots, code canaries, timings, and pointer summaries all have legitimate edge cases. Turnstile validation and browser automation flags are bot-verification gates and fail with an explicit reason. Repeated server-measured sub-two-second answers are also a hard failure.

VOUCHA currently forces honeypot and code_honeypot signals to report_only: true. A matched signal can appear in check-run summaries, risk reports, and flagged-pass labels, but it does not change the quiz score. One ambiguous clue does not change the result. Two independent interaction clues can visibly pause a correct result for independent maintainer confirmation, with an established passkey also available when enabled. Pointer summaries and code canaries never count toward that confirmation threshold.

Use code honeypots as canaries, not traps

Good code canaries are literal markers that should never appear in production code through a careful human workflow. They are useful in:

• internal examples marked as do-not-copy;
• generated fixtures that coding agents may overgeneralize from;
• repository-local prompts or scaffolding notes;
• documentation snippets that describe bad output.

Keep patterns unique, scoped, and boring. Do not publish the exact marker in PR comments if that would make the canary easy to remove. Configure paths so the scan covers the areas where copying the marker matters.

signals:
  - type: code_honeypot
    report_only: true
    patterns:
      - "VOUCHA_DO_NOT_ADD_THIS"
    paths: ["src/**", "infra/**"]

Code honeypots scan added diff lines only. Moving or deleting a marker should not count as introducing it.

Reuse issue workflow for planned work

linked_issue_match is strongest when it reflects the repository’s existing triage process:

• trusted maintainers write the issue, assign the contributor, or apply an existing planning label;
• the PR body links the issue with Fixes #123, Closes #123, or a GitHub URL;
• the configured LLM finds that the PR title, body, and changed files match the requested outcome.

VOUCHA verifies the actor in GitHub’s label or assignment event before treating it as approval. An assignment counts only when the PR author is still assigned and a write-capable maintainer made the assignment.

Keep require_same_repo: true unless cross-repo planning is a normal part of the project. Keep require_trusted_signal: true unless issue references alone are already considered enough review context.

Use path rules for real differences in risk

Avoid a single heavyweight policy for the whole repo. Use path_rules when maintainers would ask a different class of question:

• auth, permissions, billing, data deletion, and cryptography;
• database migrations and generated schema changes;
• CI, release, deployment, and infrastructure workflows;
• package manager, build, or runtime entrypoint changes.

Path rules can override gates, approval mode, attempts, cooldown, minimum changed lines, and path scope. The first matching rule wins, so order specific rules before broad rules.

Pick a draft strategy deliberately

The default template uses draft_prs: ignore, so draft PRs produce no VOUCHA check until they become ready for review. Use draft_prs: neutral when maintainers want visible check context without forcing unfinished work through a quiz. Use draft_prs: challenge only if the repository treats drafts as review-ready work.

Rechallenge only when new commits matter

The default is delta-aware: VOUCHA compares the latest passed head with the new head, ignores docs/Markdown-only follow-ups, and resets the gate for meaningful changes. The follow-up is two questions and is generated only from the new commits, not the entire PR. Use never when a repository deliberately wants a pass to survive every later push; use always when every non-ignored delta must reset it.

include_paths: ["src/core/**", "migrations/**"]
rechallenge:
  on_push: included_paths
  ignore_paths: ["docs/**", "*.md"]
  questions: 2

If include_paths is empty, included_paths behaves like always. That is a strict fallback so a typo or incomplete config does not silently preserve stale passes.

Tune output for the repository

During rollout, output.comments: normal makes the workflow easy to inspect. Use detailed briefly when maintainers need risk detail in PR comments. Use quiet for high-volume repositories where check-run output is enough.

Set output.contributor_message when the repository wants its own welcome or review language in the action-required comment. The message supports Markdown and {{author}}, {{max_attempts}}, and {{challenge_url}}; keep it short and leave policy outcomes to VOUCHA so contributors always see a clear status.

Use output.labels.failed to make failing checks visible from the PR list, output.labels.passed when successful checks should be visible there too, and output.labels.flagged as defense in depth for passed records that contain strong automation evidence. VOUCHA removes stale outcome labels as the check state changes. Inconclusive signals remain in the check-run report and never add a flagged label by themselves.

Treat large PRs as investigation problems

For large PRs, configure context.ignore_paths, map_tokens, detail_tokens, and max_files so the investigation focuses on meaningful evidence. Generated outputs, lockfiles, vendored code, and binary assets usually make poor quiz anchors.

If large PRs are common and the deployment can support it, configure the Flue investigator and keep context.investigator: auto. Normal PRs can stay on the main Worker; large PRs use the external investigator when it is available.