Whitelist Configuration for Wizard

Overview

Wizard uses a whitelist configuration file (config/whitelist.json) to control PR time tracking requirements, Goal validation behavior, and related processing rules.

Purpose

• Whitelisted Organizations: Organizations where PR time tracking is not required (except for mandatory users).
• Mandatory Users: Users who must always submit PR time, regardless of their organization.
• Excluded Users: Users who are always excluded from PR time tracking, regardless of any other conditions.
• Excluded Review Repos: Organization/repository pairs excluded from review counts only in developer stats (e.g., holdex/trial).
• Spec-Disabled Organizations: Organizations that do not use Wizard's markdown spec workflow for Goals. Goal validation skips spec-related checks and other-sections warnings for these orgs (see Effect on Goal validation).
• Excluded Organizations (per deployment environment): Organizations whose GitHub events are skipped by the webhook handler and whose data is omitted from developer stats (PRs, bugs, reviews, submissions, active days). Lists are keyed by VERCEL_ENV (production, preview, or development). This does not affect PR time tracking rules.

Configuration

File Location

• The whitelist file is named whitelist.json and is located in the config/ directory.
• The mandatory users are configured in the team-members.json file in holdex/hr-internal (HR access only).

File Format

The config/whitelist.json file follows this structure:

{
  "whitelistedOrganizations": ["org-name-1", "org-name-2"],
  "specDisabledOrganizations": ["org-name-1"],
  "excludedUsers": ["username-1", "username-2"],
  "excludedReviewRepos": ["org/repo-1", "org/repo-2"],
  "excludedOrganizations": {
    "production": ["org-name-3", "org-name-4"],
    "preview": ["org-name-5", "org-name-6"],
    "development": []
  }
}

The team-members.json file in holdex/hr-internal follows the structure documented in config/team-members.json.example in this repository.

excludedOrganizations and VERCEL_ENV

Each key under excludedOrganizations must match the deployment’s VERCEL_ENV value:

Wizard reads excludedOrganizations[VERCEL_ENV] at runtime. An org listed only under production is ignored on production but still processed on preview and local dev (if not listed under those keys).

Updating the Whitelist

To update the whitelist:

1. Open the config/whitelist.json file.
2. Add or remove organizations under whitelistedOrganizations.
3. Add or remove organizations under specDisabledOrganizations for orgs that do not use markdown specs in Goals.
4. Add or remove users under excludedUsers.
5. Add or remove org/repo pairs under excludedReviewRepos (repos where reviews shouldn't count toward stats).
6. Add or remove organization slugs under the appropriate excludedOrganizations key (production, preview, or development).
7. Save the file and deploy so the running instance picks up the change.

Effect on processing and stats

• excludedReviewRepos only affects review-related metrics (e.g. reviews, total_reviews); other stats from those repos are still counted.
• excludedOrganizations.<vercel-env> for the current deployment:
  • Webhooks (when NODE_ENV is production): GitHub events from listed orgs are dropped before Trigger.dev tasks run.
  • BigQuery / developer stats: events from listed orgs are filtered out of queries (PR merges, bug events, reviews, submissions, active days).

Use different keys when you need different behavior per environment—for example, exclude a dev playground org on production only so preview and local instances can still process it.

Effect on Goal validation

For organizations listed in specDisabledOrganizations, Wizard skips markdown-spec validation when processing Goal and Draft Goal issues:

• Spec section: no auto-creation of docs/specs/*.md on goal open, and no validation of the # Spec section or spec document URLs.
• Other sections: no warnings for content between standard sections (e.g. orphan prose or content without a top-level # heading). These checks assume the standard Goal layout that includes a Spec section.
• Still validated: deadline (ETA) and Stakeholders Interview sections continue to run as usual.

This list is independent of whitelistedOrganizations. An org can be whitelisted for PR time tracking and spec-disabled for Goals at the same time.

The @holdex goal create-spec command is not blocked for spec-disabled orgs; it remains available for manual spec creation when needed.

To update the mandatory users:

1. Open team-members.json in holdex/hr-internal.
2. Set isMandatory to true for the users that must always submit PR time.
3. Save the file — the change takes effect on the next production deployment.

Behavior Scenarios

Excluded Users

If a user is in the excludedUsers list, they will always be excluded from PR time tracking requirements, regardless of their organization or mandatory status. This takes precedence over all other rules.

Organization and Mandatory User Rules

For users not in the excluded list, the following rules apply:

Example Scenarios

1. UserA is in excludedUsers → UserA is never required to submit PR time.
2. Organization A is whitelisted, and UserB is not mandatory or excluded → UserB does not need to submit PR time.
3. Organization A is whitelisted, but UserC is mandatory and not excluded → UserC must submit PR time.
4. Organization A is not whitelisted, and UserD is not mandatory or excluded → UserD must submit PR time.

Notes

• Excluded users are always exempt from PR time tracking requirements
• Mandatory users must submit PR time unless they are in the excluded list
• For any issues or questions, please contact the project maintainer.