Stage: discover_scope

Runtime config (canonical): workflow.json → stages.discover_scope

Purpose: Read the repo and interview the user to determine which regulations apply to this release, then produce scope.md — applicable regulations plus a numbered checklist (C1, C2, …) of concrete, testable requirements that downstream stages will audit and fix against. Output artifact: write to the absolute path provided in your I/O context (the scope.md body lives in the artifact body — the artifact IS scope.md for this workflow). Valid results this stage writes: pending (drafting / awaiting user answers), done (scope finalized).

This is an interruptible inline stage. The stop hook allows natural pauses for Q&A.

You are the main agent. Read state.md for the current epoch. Then immediately write the artifact at the path shown in your I/O context with result: pending so the stop hook knows the stage is in progress. Iterate the body in place; flip result: to done only when the scope checklist is locked.

Inputs

Read every input from the path shown in your I/O context — never construct or hardcode paths.

• Required: release_target run file — the snapshot of detected manifests, store metadata, deployment regions, and SDKs captured at workflow start. Read this first; it answers many questions you would otherwise have to ask.

Protocol

1. Read the snapshot, then explore

Read the release_target run file. Then look at the repo directly to fill in gaps:

• App type / platform: AndroidManifest.xml, Info.plist, package.json, app.json, next.config.*, vercel.json, Dockerfile, etc.
• Store metadata (if mobile): fastlane/metadata/, metadata/, app/src/main/play/, listing-text files
• Privacy posture: any privacy*.md, PRIVACY*, app-privacy.json, App Store privacy plist entries
• SDKs / third-party data flow: dependency manifests (Podfile.lock, app/build.gradle, package.json, requirements.txt, pyproject.toml, go.mod)
• Deployment regions / data residency: env files, vercel.json, wrangler.toml, fly.toml, IaC under terraform/, infra/
• Auth / payments / minors-related code: search for stripe, paypal, coppa, age, gdpr, ccpa, cmp, consent, analytics

2. Interview the user — cap at 5 questions total

Ask ONLY what the snapshot + repo can't determine. Cover (in priority order, as needed):

1. Target markets / jurisdictions (e.g. EU, UK, US, California specifically, China, Brazil, India, global)
2. Industry vertical (e.g. consumer social, fintech, healthtech, edtech, gambling, adtech, B2B SaaS, kids/family)
3. Age target (general audience, 13+, under-13, mixed — drives COPPA / age-gating / parental consent)
4. Release cadence (one-shot, weekly, continuous; dictates how strict the gate vs how often re-run)
5. Any known prior compliance commitments (existing DPA, certifications like SOC2/ISO 27001, prior privacy review)

Rules:

• One question per message, multiple-choice (A/B/C/...) wherever possible.
• STOP and wait for the user's reply after each question — the stop hook handles the pause.
• Cap at 5 questions total. If after 5 you still have unknowns, note them in ## Open assumptions of scope.md with conservative defaults (e.g. "assumed EU + US scope; re-run with explicit markets if narrower").
• Skip questions the snapshot already answered.

3. Determine applicable regulations

Based on app type, markets, industry, and age target, list every regulation that applies. Common ones (non-exhaustive — add what applies):

• Privacy / data protection: GDPR (EU), UK GDPR, CCPA/CPRA (California), VCDPA (Virginia), CPA (Colorado), LGPD (Brazil), PIPL (China), PIPEDA (Canada), APPI (Japan), POPIA (South Africa)
• Children: COPPA (US under-13), GDPR-K (EU under-16/varies), UK Age-Appropriate Design Code, California AADC
• Store policies (functional law for mobile): Apple App Store Review Guidelines, Google Play Developer Program Policies (incl. Data Safety, Families Policy, Permissions)
• Accessibility: WCAG 2.1/2.2 AA (often referenced by ADA, EN 301 549, EAA)
• Sector-specific: HIPAA (US health), GLBA (US finance), PCI-DSS (payments), SOX (public-company financial controls), FERPA (US education), KYC/AML (fintech)
• Content / advertising: FTC Endorsement Guides, EU DSA, EU AI Act (if AI features), gambling-license rules
• Telecom / messaging: TCPA, CAN-SPAM, CASL
• Cookies / tracking: ePrivacy (EU), App Tracking Transparency (iOS)

4. Produce the numbered checklist

For every applicable regulation, derive concrete, testable requirements. Each item is one row, numbered C1, C2, … and includes:

• C-ID (e.g. C7)
• Regulation reference (e.g. GDPR Art. 13, App Store Guideline 5.1.1(i), COPPA §312.4)
• What to check — phrased as a yes/no auditable claim
• Where in the repo — concrete file paths / globs / search terms the auditor should examine

Each item must be independently auditable by reading code/config — no item should require running the app or interviewing humans again.

5. Write scope.md (the artifact body)

---
epoch: <epoch from state.md>
result: done
---
# Scope — <App name or repo>

## Release target snapshot
<2–4 lines: app type, primary platform, target markets, age target, industry, release cadence>

## Applicable regulations
- <Regulation 1> — why it applies (1 line)
- <Regulation 2> — why it applies
- ...

## Open assumptions
> Items the user couldn't confirm in 5 questions. Auditor treats these as in-scope by default; user can override on a re-run.
- <assumption 1>
- ...

## Compliance checklist

| C-ID | Regulation | What to check | Where in repo |
|------|------------|---------------|---------------|
| C1   | <ref>      | <yes/no claim>| <paths/globs/search terms> |
| C2   | ...        | ...           | ... |
| ...  | ...        | ...           | ... |

## Notes for the auditor
<Any context the auditor needs that doesn't fit a single C-ID — e.g. "this app uses a custom analytics SDK at packages/analytics; treat all data exports through that module as in-scope".>

6. Confirm with the user, then finalize

Show the user the full checklist (or a summary if very long) and ask:

"Scope locked: <N> checklist items across <K> regulations. Confirm to proceed to audit, or call out any items to add/remove/adjust."

If they request changes, iterate on the body — keep result: pending. Once they confirm, edit the artifact: change result: pending → result: done.

That's the only action needed here. The main loop's stage-runner reads the artifact's result: and calls update-status.sh to advance to audit.

Rules

• Do NOT exceed 5 user questions. Use conservative defaults for residual unknowns and document them under ## Open assumptions.
• Do NOT generate vague checklist items ("be GDPR compliant"). Every C-ID must be a yes/no claim auditable from files.
• Do NOT skip the "Where in repo" column — the auditor relies on it to gather verbatim evidence.
• Do NOT call update-status.sh from this stage — that's the main loop's job.