Phase 2A: define opportunity discovery architecture

[abdo2006-dev]

Summary

Documentation-and-architecture PR only. Records the decisions Phase 2A (Opportunity Discovery MVP)
implementation depends on, before any schema, adapter, or UI code is written. No database
migration, dependency, adapter, HTTP source request, ingestion run, stored listing, UI feature,
GitHub setting, or cloud resource is introduced by this PR.

Decisions changed / recorded

• ADR-016 (new): TypeScript for opportunity ingestion and deterministic scoring, supersedes
  ADR-003 for that scope only. The realistic Phase
  2A workload (fetch JSON, validate, normalize, sanitize, hash, upsert) doesn't need Python's
  data/ML ecosystem, and the two realistic future hosted execution targets (Supabase Edge
  Functions, Cloudflare Workers) both run TypeScript natively. Phase 1B resume parsing and Phase 6
  market aggregation remain open, separately-decided questions — this ADR does not resolve them.
• ADR-017 (new): local-first ingestion execution — an explicit, owner-run local CLI, not a
  GitHub Actions schedule. Decisive reason: no hosted Supabase project exists yet, so a cloud
  runner has nothing reachable to write to. Records the later migration path (Supabase Edge
  Function → Cloudflare Worker → last-resort scheduled container) and its trigger conditions, none
  provisioned now.
• ADR-018 (new): manually entered opportunities are private, user-owned rows in a new
  private_opportunities table — structurally separate from the shared, service-role-written
  opportunity-identity domain, not a nullable-owner column on opportunities. This resolves the
  open question the prior planning pass left unsettled, and retires the informal "manual source /
  import_manual_opportunity RPC" sketch from that pass in favor of the smallest-blast-radius RLS
  shape (matches the existing work_experience template exactly).
• Cross-reference notes added to ADR-002, ADR-006, ADR-010 recording how each relates to the
  new decisions, without altering their own Accepted/Proposed decisions.
• ARCHITECTURE.md, DATA_MODEL.md, RLS_POLICY_MATRIX.md, SECURITY_AND_PRIVACY.md,
  TESTING_STRATEGY.md, USER_WORKFLOWS.md, DEVELOPMENT_ROADMAP.md, DEPLOYMENT_STRATEGY.md,
  COST_MODEL.md, OBSERVABILITY.md, MVP_SCOPE.md, DATA_FLOW.md updated so no diagram or prose
  still presents scheduled GitHub Actions Python ingestion as active or guaranteed. One real
  fragility is called out more honestly than before: the Supabase free-tier pause mitigation
  previously assumed scheduled jobs would keep the project warm — under manual local execution
  that mitigation doesn't apply, so this is currently a bigger risk, not a smaller one.
• New docs/INGESTION_ARCHITECTURE.md: adapter/orchestrator interface, identity/dedup and
  conservative freshness/closure rules, sanitization, the first-adapter choice (Greenhouse) and why,
  the manual-import/SSRF boundary, and the binding source-onboarding checklist.
• New docs/DATA_SOURCES_AND_COMPLIANCE.md: dated (2026-08-03), evidence-labeled source matrix
  — Greenhouse (implement first), Lever/Personio (candidates for later), Workable (rejected on
  measured 108 MB/refresh bandwidth, not compliance), SmartRecruiters (blocked pending
  clarification — documented API vs. a robots.txt disallowing all agents but one), Bundesagentur
  für Arbeit (do not use — its own terms of use explicitly prohibit this), Make it in Germany
  (inherits that restriction), Workday's undocumented internal endpoint (do not use), EURES
  (licensed/partner-only), EURAXESS (manual import only), and every researched target-employer
  career site.

Correction: personal-first implementation priority

A follow-up commit (docs: prioritize the personal opportunity MVP) records an explicit
product-priority correction from the repository owner: CareerOS is currently personal-first,
single-owner, and local-first, and the immediate priority is a genuinely useful working
opportunity-discovery and application-tracking system — not extensive preparation for hypothetical
future users.

• New personal-first policy (MVP_SCOPE.md): until the owner validates real-world usefulness,
  prioritize working product features over speculative multi-user/enterprise concerns (no admin
  roles, teams, orgs, public registration, abuse prevention, or quotas at this stage). A practical
  effort guideline is recorded (~70% product functionality, ~20% correctness/tests, ≤10% essential
  security/auth work absent a concrete blocker). Explicitly not a relaxation of secret handling
  or personal-data privacy — the safeguards that were already non-negotiable stay non-negotiable.
• Phase 2A PR sequence revised (DEVELOPMENT_ROADMAP.md): the previous 2A.1
  (opportunity-foundation-only, empty screens) / 2A.2 (Greenhouse adapter) split is combined into a
  single Phase 2A.1 — Personal Opportunity MVP, on the reasoning that a feature isn't useful
  merely because tables and empty screens exist. The former 2A.3 (explainable ECE relevance) is
  renumbered to 2A.2; every cross-reference across the docs set and ADR-016 is updated
  accordingly.
• Application tracking pulled into the first milestone's exit condition, not a separate later
  phase (the old, now-redundant "Phase 4 — Save, track, act" roadmap phase is marked absorbed, not
  deleted, so history stays traceable). DATA_MODEL.md's applications table gains: an expanded
  status enum (preparing → applied → awaiting_response → interview_scheduled → interview_complete → offer → accepted / rejected / withdrawn / closed), status_updated_at,
  optional next_action/next_action_due_at, notes, and contact_note — current-status-plus-
  timestamps, deliberately not a full event-sourced history.
• Pinned listing content for both shared and private opportunities: a shared opportunity's
  applied-to content was already pinned via the existing saved_opportunities .saved_opportunity_version_id → immutable opportunity_versions. A private, manually entered
  opportunity had no equivalent guarantee — private_opportunities is ordinary mutable CRUD, not
  versioned — so applications gains private_opportunity_id plus a private_opportunity_snapshot_jsonb
  captured once at application-creation time; a later edit to the private entry (fixing a typo,
  updating a copied deadline) never rewrites what the application and interview-prep notes refer
  to. Exactly one of saved_opportunity_id / private_opportunity_id is set per row. This is a
  targeted addition to DATA_MODEL.md/USER_WORKFLOWS.md, not a broader schema redesign.
• Reduced, explicit testing scope for Phase 2A.1-sized feature work (TESTING_STRATEGY.md §10,
  appended so existing anchors referenced elsewhere in the docs are not disturbed): essential
  per-table RLS/API/frontend checks remain required (owner CRUD, one representative cross-user
  denial, browser-cannot-write-shared-records, version/snapshot pinning, real primary workflows).
  Exhaustive privilege-permutation matrices, admin-role testing, public-registration abuse testing,
  and multi-tenant isolation testing are explicitly deferred until they would actually apply.
  Privileged functions and new external-content trust boundaries still get focused tests when
  actually introduced — this narrows breadth for ordinary CRUD, not depth where real risk exists.
• Source-compliance conclusions (Greenhouse first, Lever/Personio later, Workable rejected,
  SmartRecruiters blocked, BA/Make-it-in-Germany excluded, manual-import-only sources, no live
  network dependency in CI) are unchanged — no further source research was performed in this
  correction.

Explicit absence of runtime implementation

No SQL migration, no ingestion/ code, no HTTP request beyond this research pass's own read-only
verification, no manual-import RPC, no opportunity UI, no search, no ranking, no stored listing, no
cloud resource. git diff --stat against main touches only files under docs/.

Test plan

• git status/git diff --check clean; no whitespace errors
• Relative markdown links in every changed file resolve to existing files
• Heading-anchor fragments in every changed file resolve against GitHub's actual slug algorithm
  (verified with a corrected slugifier after an initial false-positive; one real bug found and
  fixed — a stray (#) placeholder self-link)
• ADR index (docs/adr/README.md) lists all 18 ADRs with consistent status/title/number;
  unaffected by the corrective commit (no ADR added or resolved by it)
• All 5 mermaid diagrams in changed files rendered with mmdc (mermaid-cli 11.16.0); 4 render
  cleanly. The 5th (DATA_FLOW.md's main sequence diagram) fails to parse — confirmed pre-existing
  on main at 5c3f20c, unrelated to this PR's edits (a semicolon inside a message label). Not
  fixed here (out of scope); flagged separately.
• .github/workflows/ci.yml parses as valid YAML; unchanged by this PR; all 5 uses: actions
  remain SHA-pinned
• Secret scan and absolute local-path scan on the diff: clean
• Tracked-file hygiene: no node_modules/dist/.env in the diff
• Frontend regression (unaffected by this docs-only PR, run to confirm no incidental breakage):
  format:check, lint, typecheck, build all clean. test: 52/53 passing locally — the one
  failure was a 5s test-timeout in SignInPage.test.tsx that reproduced against two different
  tests across repeated local runs (a local-machine timing flake, not a deterministic failure tied
  to any change in this PR, which touches no app/ source); GitHub Actions' frontend job is
  authoritative and is tracked below.
• CI (GitHub Actions frontend/database jobs) — both passed after the initial two commits;
  re-verified after the corrective commit