internship-job-automation

Imported from cristhianparedes0924-web/internship-job-automation (AGENTS.md). Install upstream with npx skills add cristhianparedes0924-web/internship-job-automation. Copyright stays with the author.

AGENTS.md

Project Purpose

• This repo is an internship job automation tool for two separate tracks:
  • Business Analytics
  • Finance
• It is not a blind mass-application bot.
• The goal is safe, explainable, track-aware internship processing with human review where needed.

Source Of Truth

• Read-only authoritative docs live in source_docs/.
• If code, tests, comments, or assumptions conflict with source_docs/, the source docs win.
• Source-of-truth files:
  • source_docs/non_negotiable_rules_updated.md
  • source_docs/application_answers_bank (1).md
  • source_docs/master_spec_updated.md
  • source_docs/build_roadmap.md
  • source_docs/business_analytics_profile_updated.md
  • source_docs/finance_profile_updated.md
  • source_docs/Cristhian_Paredes_MSF_MSBA_Resume.pdf
  • source_docs/business_analytics_cover_letter_sample.pdf
  • source_docs/finance_cover_letter_sample.pdf

Conflict Resolution Priority

1. source_docs/non_negotiable_rules_updated.md
2. source_docs/application_answers_bank (1).md
3. source_docs/master_spec_updated.md
4. source_docs/build_roadmap.md
5. source_docs/business_analytics_profile_updated.md
6. source_docs/finance_profile_updated.md
7. Approved material files in source_docs/ as reference assets

Core Agent Rules

• Keep Business Analytics and Finance logic separate from the start.
• Do not merge BA and Finance into one generic scorer, selector, strategy, packet builder, or reporting path.
• Do not invent personal facts, qualifications, dates, work authorization wording, GPA, compensation expectations, or sensitive answers.
• Only use candidate facts and answer policies that are explicitly approved in the answer bank.
• Any unresolved value or [FILL IN] marker must fail closed and surface review.
• Prefer assisted-submit over blind automation.
• Never hide failures. Stop safely, log the reason, and surface the issue clearly.
• Keep important actions logged and explainable.
• Do not jump ahead to live scraping, browser automation, Playwright flows, assisted-submit execution, or auto-submit unless explicitly instructed and the roadmap phase supports it.
• Do not modify source_docs/.
• Work inside the current WSL repo. Do not use Windows path-bridging, mklink, net use, PowerShell drive mapping, or similar filesystem link commands unless explicitly requested.

Approved Materials Policy

• The active runtime resume policy comes from source_docs/application_answers_bank (1).md.
• Use only the approved resume: Cristhian_Paredes_MSF_MSBA_Resume.pdf.
• Track profile resume families are informational only until explicitly approved for runtime use.
• Do not automatically redesign, rewrite, or switch resumes.
• Do not auto-submit a cover letter unless it is required, strategically beneficial, or explicitly approved.
• Do not generate or upload a cover letter unless a later phase explicitly approves a concrete file and workflow.

Destination-Aware Policy

• Always distinguish:
  • discovery source
  • final application destination
• LinkedIn, Indeed, and Handshake are discovery and application entry points, not guaranteed final destinations.
• If the final destination is unresolved, unsupported, or not confidently explained, pause rather than proceed.
• Never treat source-platform apply and final ATS apply as separate submissions for the same opportunity without explicit review.

Implementation Workflow

• Follow the roadmap in order.
• Prefer the smallest safe step that still meaningfully advances the current phase.
• Change only the files required for the task unless explicitly instructed otherwise.
• Keep code modular, explicit, and testable.
• Add tests for important logic.
• Prefer targeted phase-specific checks over broad reruns when the task scope is narrow.
• If a task adds or changes a CLI, run a --help smoke check.
• Avoid overengineering.
• Do not redesign unrelated code.
• Preserve clear logging around important actions and decisions.

Current Repo State

• Persistence layer exists for the Phase 1 schema and repositories (11 tables including outcomes).
• Structured config parsing and validation exist for the source docs.
• Fixture-based ingestion exists for LinkedIn, Indeed, and Handshake, plus local JSON batch ingestion.
• Phase 4 screening exists with deterministic dedupe-prep, conservative eligibility screening, persisted screening decisions, and a local runner.
• Phase 5 track classification exists with separate Business Analytics and Finance rule modules, persisted classification results, and a local runner.
• Phase 5 fit scoring exists with separate Business Analytics and Finance scoring modules, persisted fit-score results, and a local runner.
• Phase 6 destination resolution exists with persisted results and a local runner.
• Phase 7 conservative routing exists with persisted submission-lane results and a local runner.
• Phase 8 conservative materials selection exists with persisted selected-materials results and a local runner.
• Phase 9 assisted-submit packet preparation exists and remains review-oriented and artifact/report based.
• Phase 9 local form-schema mapping exists and produces reviewable action plans from local form fixtures.
• Phase 9 local assisted-submit execution exists (local-only, fixture-based, stops before submission).
• Phase 9 local interaction trace exists (ordered, reviewable trace of all execution actions).
• Phase 9 conservative textarea and checkbox support exist for exact-safe cases only.
• Phase 9 local page/section review checkpoints exist and block advancement until explicit reviewer acknowledgment.
• Phase 9 local checkpoint replay exists (resume from blocked checkpoint after acknowledgment).
• Phase 9 has a passing end-to-end acceptance test for a low-risk local assisted-submit flow.
• Phase 10 outcome storage exists with a conservative taxonomy (pending/submitted/interview/rejection/offer/etc.).
• Phase 10 analytics module exists with batched context loading (N+1 queries eliminated), response rates by track/platform/resume family/destination type, submit/pause/skip counts, and track-separated reporting (BA and Finance remain independently reviewable).
• Phase 10 review queues exist for failed submissions (structured prefix matching), unresolved destinations, and high-value manual jobs.
• Phase 10 daily and weekly summary generation exists.
• Phase 10 CLI exists for recording outcomes, generating analytics reports, review queues, and summaries. Supports --format json|markdown|both for report output.
• Phase 10 Markdown formatters exist for daily/weekly summaries, analytics reports, and review queue overviews.
• Phase 10 hardening is complete: analytics are efficient, review queues are safer, JSON and Markdown reports exist, local fixture data remains distinct.
• Phase 11 preparation scaffolding exists (non-operational, policy-only):
  • Auto-submit eligibility policy module evaluates 10+ blocking criteria.
  • Destination readiness/support model with per-destination-type support levels.
  • Kill-switch configuration (global, per-destination, per-track) with evaluation service.
  • Rate-control configuration (global, per-platform, per-destination, per-track) with evaluation service.
  • Verification status, rollback reason, and safety monitoring decision models exist as future interfaces.
  • Phase 11 readiness report service generates JSON and Markdown reports of eligibility across all jobs.
  • Phase 11 CLI exists with readiness-report and eligibility-check subcommands.
• Phase 11 execution Step 1 — first guarded auto-submit slice (native LinkedIn only):
  • Guarded executor orchestrates: duplicate guard → gate check → browser interaction → field safety screening → verification with evidence → persistence.
  • Browser interaction is behind a LinkedInBrowserDriver Protocol for testability.
  • Real Playwright-based LinkedIn driver exists (linkedin_driver.py) for Easy Apply flows.
  • dry_run is the default mode; live mode requires explicit --confirm-live opt-in.
  • Sensitive fields (criminal, disability, salary, essay, cover letter, legal attestation) always stop execution.
  • Unsupported field types or labels (textarea, writing sample, portfolio) cause safe fallback.
  • Post-action verification produces conservative evidence (safe markers, no screenshots, no broad page content).
  • Granular Phase 11 attempt statuses: dry_run_completed, dry_run_blocked, live_submit_verified, live_started, live_paused_for_review, live_failed_navigation, live_failed_verification, live_fallback_required, live_stopped, live_error, gates_blocked, duplicate_blocked, live_blocked_pre_execution.
  • All phase11_* statuses are distinct from local_fixture_execution_* statuses; local fixture/replay history is never treated as real submission.
  • Duplicate/already-applied guard blocks live execution when a verified submission or ambiguous prior live attempt exists; dry_run is still allowed.
  • Fallback classification is precise: sensitive_question, unsupported_control, unsupported_prompt, verification_inconclusive, destination_or_policy_issue, duplicate_or_ambiguous_submission_state.
  • Phase 11 execution CLI exists with dry-run and execute subcommands; reports include execution mode, gate results, duplicate check, verification status, evidence summary, fallback classification, and answer resolution summary (resolved/blocked counts with source info).
  • Native LinkedIn answer-resolution adapter maps LinkedIn Easy Apply field labels to approved canonical answers from the Phase 9 answer bank.
    • Only APPROVED_SAFE + HIGH confidence fields are auto-filled in live mode.
    • REVIEW_REQUIRED fields (GPA, work auth, relocation, compensation) block live auto-fill.
    • UNAVAILABLE fields (unresolved [FILL IN] placeholders) block live auto-fill.
    • Ambiguous/unmapped labels block with explicit reason.
    • Sensitive fields (criminal, disability, veteran, salary, demographic) are never auto-filled.
    • Label matching uses a deterministic pattern table — no fuzzy matching or ML.
  • Outcome bridge maps Phase 11 execution outcomes to Phase 10 analytics layer:
    • LIVE_SUBMITTED → submitted, LIVE_ERROR/LIVE_FAILED_NAVIGATION → failed_submission, GATES_BLOCKED/DRY_RUN_BLOCKED/DUPLICATE_BLOCKED → skipped, LIVE_STOPPED_*/LIVE_PAUSED → paused_for_review.
    • Dry-run results are NOT bridged (inspection only, not real submission).
  • All tests use a FakeLinkedInDriver — no live browser sessions in CI.
  • Screenshots are not required.
  • Phase 11 native_linkedin scope is COMPLETE for the bounded happy path (field detection → answer resolution → auto-fill → submit → verify → persist → analytics bridge).
  • Broader multi-site Phase 11 rollout is NOT implemented.
• Work remains conservative and review-oriented. Only native LinkedIn low-risk flows are in scope.
• Source docs currently still contain unresolved placeholders, so fail-closed behavior remains required.
• Local fixture execution and replay history are clearly distinguished from real submitted applications.
• Current local ingestion fixture format is one JSON file per job with:
  • source_platform
  • source_url
  • payload

Local Development Commands

• Install deps: python -m pip install -r requirements.txt
• Run focused tests: IJA_LOG_LEVEL=CRITICAL PYTHONPATH=src .venv/bin/python -m pytest -q --capture=sys <targeted-tests>
• Initialize the DB: PYTHONPATH=src .venv/bin/python -m internship_job_automation.db.init_db
• Run structured-config app entry point: PYTHONPATH=src .venv/bin/python -m internship_job_automation
• Run local fixture ingestion CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.ingestion --input <fixture.json-or-dir>
• Run screening CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.screening --help
• Run classification CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.classification --help
• Run scoring CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.scoring --help
• Run destination-resolution CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.destination_resolution --help
• Run routing CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.routing --help
• Run materials-selection CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.materials_selection --help
• Run assisted-submit CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.assisted_submit --help
• Run assisted-submit execution CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.assisted_submit.execution_cli --help
• Run form-mapping CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.form_mapping --help
• Run analytics CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.analytics --help
• Run Phase 11 prep CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.phase11_prep --help
• Run Phase 11 execution CLI: PYTHONPATH=src .venv/bin/python -m internship_job_automation.phase11_execution --help

Expected Codex Response Format

• For coding tasks, report:
  1. files changed
  2. what was implemented
  3. assumptions
  4. risks
  5. tests run
  6. next smallest safe step

AGENTS Style

• Keep future updates compact, practical, and easy to scan.
• Prefer bullets over long prose.
• Do not include private chain-of-thought.
• Do not speculate beyond the roadmap.