compliance-discover

name

compliance-discover

description

Run compliance-discovery sources against the configured nonprofit entity and report findings. Use this skill when the user asks "are we compliant?", "check our IRS status", "verify our tax-exempt status", "run a compliance check", "is our 501(c)(3) still active?", or when they want to refresh the compliance picture before a board meeting, audit, or grant application. Phase 3 covers IRS TEOS/BMF, public CA AG Registry Search Tool/detail pages, public CA SOS bizfile checks, public CA FTB Entity Status Letter checks, public CDTFA permit verification, and user-assisted authenticated CA portal checks.

Compliance Discovery

Runs every registered compliance source for the onboarded nonprofit, captures each run in BigQuery (compliance.discovery_runs), records typed findings (compliance.findings), and prints a markdown report.

Keep this file focused on the discovery workflow. Source-specific and jurisdiction-specific details live in references/ and should be loaded only when the user's question or the current report needs that detail.

Reference files

• references/manual-sources.md - use when a report contains MANUAL, BLOCKED, or AUTH sources, or when the user asks how to complete a source by hand.
• references/california-sources.md - use for CA AG Registry, CA AG Online Renewal, CA SOS bizfile, CA FTB Entity Status Letter, MyFTB, and CDTFA details.
• references/federal-sources.md - use for IRS TEOS, IRS EO BMF, and IRS Tax Pro Account source decisions.

Pre-flight

The user must have completed onboarding (see compliance-onboard). If runDiscovery returns not_onboarded, walk the user through onboarding first.

The skill provisions the compliance BigQuery dataset and tables itself (idempotently) before running any sources. Do not ask the user to run a migration script first.

Wiring

Call runDiscoveryProduction from src/compliance/skills/discover-wiring.ts:

import { runDiscoveryProduction } from '../../src/compliance/skills/discover-wiring.ts'

const result = await runDiscoveryProduction({ projectId })

That call constructs GCP clients, builds the recorder, registers the default compliance jurisdictions (usFederalJurisdiction and usCaJurisdiction), runs the schema migration, and dispatches every source.

For shell use:

bun scripts/compliance-discover.ts --project <gcp-project-id>

Add --json for the full structured report.

Report to the user

Use formatDiscoveryReport from src/compliance/skills/discover-report.ts. The report shows:

• Overall completeness.
• An Action Required section whenever actionable manual-required or auth-required sources remain.
• Per-source state: OK, MANUAL, BLOCKED, AUTH, or ERROR.
• CA AG status comes from the public Registry Search Tool source. The CA AG Online Renewal System is optional dashboard-only detail and should not be presented as a manual/authenticated status check unless the user explicitly asks for those dashboard details.
• For MANUAL sources: why automation is unavailable, the official URL to open, manual steps with the configured values already filled in, and human-readable result labels to report back.
• For AUTH sources: login URL, source terms URL, read-only setup steps with configured identifiers already filled in, human-readable result labels, and forbidden actions.
• Findings ordered by severity, then jurisdiction, then source.

Tell the user that successful, failed, manual-required, policy-blocked, and auth-required source outcomes are persisted in compliance.discovery_runs, and findings are persisted in compliance.findings.

If the report contains Action Required, relay that section to the user as the next step and ask them to complete the listed manual/auth checks. Do not stop at a machine summary of source statuses. The skill is responsible for walking the user through the remaining manual work after automatic discovery finishes.

Before replying with a manual or authenticated next step, run discovery or use the freshly generated discovery report and treat the Action Required section as the source of truth. Do not handwrite the step from memory. The reply is incomplete unless it includes:

• The official URL the user must open.
• The exact action to take on that site.
• Every relevant identifier or value printed by the report, including legal entity name, FEIN, state registration details, mailing address, CA SOS number, CA AG number, FTB entity ID/name, CDTFA identifiers, IRS ruling date, and CA AG registry dates when available.
• The exact information the user should report back in plain language.
• No raw source IDs or evidence-field keys.

Do every check the code can perform before asking the user to do anything. For each manual/auth source, give the exact official URL and the exact value the user should enter when it is configured, such as the SOS entity number, AG charity number, FTB entity ID, or CDTFA account identifier. Do not say "enter the configured ID" when the ID is known.

Use human names in user-facing instructions: for example, say "CA CDTFA Permit, License, or Account Verification," not us-ca/ca-cdtfa-permit-license-verification. Do not ask the user to fill raw evidence-field keys such as entity_status; ask for "entity status" in a plain sentence instead. Accept plain sentences or bullets from the user and map them to the internal evidence fields yourself.

When an actionable source is not OK, do not summarize it as compliant. For manual-required and auth-required sources, keep the instructions concise, clear, and written as full sentences. If the user returns manual or authenticated evidence, do not claim it was persisted unless a dedicated evidence-ingestion path has been implemented and successfully run. The current ingestion path is bun scripts/compliance-record-evidence.ts --project <gcp-project-id> --source <source-id> --evidence-file <json-file>; map the user's plain-language answer into the source's evidence field keys yourself before running it.

Failure modes

If runDiscoveryProduction returns:

• not_onboarded - direct the user to compliance-onboard.
• load - entity rows, identifiers, or schema migration failed to load.
• persist - derived findings could not be written.
• wiring - jurisdiction registration failed.

Per-source outcomes include:

• source_failure - source was unreachable, rate-limited, invalid, or changed schema.
• manual_required - source policy requires manual evidence capture.
• policy_blocked - source cannot be read under current policy.
• auth_required - source requires a user-assisted authenticated session, credentials, MFA, or portal access before it can be treated as checked.

Do not treat a failed, blocked, manual-required, or auth-required source as an all-clear, except for us-ca/ca-ag-online-filing, which is optional dashboard-only detail because CA AG public status is checked by us-ca/ca-ag-registry.

Source code

• src/compliance/skills/discover-wiring.ts - production wiring.
• src/compliance/skills/discover.ts - orchestration logic.
• src/compliance/skills/discover-report.ts - markdown report formatter.
• src/compliance/rules/findings.ts - Phase 2 findings/gap engine.
• src/compliance/jurisdictions/ - jurisdiction modules and source definitions.
• scripts/compliance-discover.ts - CLI wrapper.