{"id":50428476,"url":"https://github.com/jc1122/metaopt-preflight","last_synced_at":"2026-05-31T12:02:13.027Z","repository":{"id":351159970,"uuid":"1209807822","full_name":"jc1122/metaopt-preflight","owner":"jc1122","description":"One-shot preflight skill for ml-metaoptimization campaigns — validates repo structure, bootstraps .ml-metaopt/ dirs, checks backend readiness","archived":false,"fork":false,"pushed_at":"2026-05-24T18:57:14.000Z","size":215,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-24T20:29:28.817Z","etag":null,"topics":["ai-agents","automation","github-copilot","leaf-skill","machine-learning","metaoptimization","preflight","skill"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jc1122.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T19:56:59.000Z","updated_at":"2026-05-24T18:57:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jc1122/metaopt-preflight","commit_stats":null,"previous_names":["jc1122/metaopt-preflight"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jc1122/metaopt-preflight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jc1122%2Fmetaopt-preflight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jc1122%2Fmetaopt-preflight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jc1122%2Fmetaopt-preflight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jc1122%2Fmetaopt-preflight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jc1122","download_url":"https://codeload.github.com/jc1122/metaopt-preflight/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jc1122%2Fmetaopt-preflight/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33730241,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","github-copilot","leaf-skill","machine-learning","metaoptimization","preflight","skill"],"created_at":"2026-05-31T12:02:12.336Z","updated_at":"2026-05-31T12:02:13.017Z","avatar_url":"https://github.com/jc1122.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# metaopt-preflight\n\nCodex-usable, one-shot preflight for [ml-metaoptimization](https://github.com/jc1122/ml-metaoptimization) campaigns.\n\n## What it does\n\nRun this once before starting an `ml-metaoptimization` campaign. It evaluates\nrepository, backend, and environment readiness; may scaffold the local\n`.ml-metaopt/` workspace when repo prerequisites are missing; and emits the\nreadiness artifact consumed by `LOAD_CAMPAIGN`.\n\nThis is a one-shot invocation with no resume path. Re-run it from scratch when\nthe environment changes or the campaign configuration changes.\n\n## Prerequisites\n\n- Python 3.10+\n- PyYAML ≥ 6.0 (installed via `requirements.txt`)\n- [ml-metaoptimization](https://github.com/jc1122/ml-metaoptimization) campaign YAML\n- SkyPilot with Vast.ai provider — `pip install 'skypilot[vast]'`\n- WandB credentials — `WANDB_API_KEY` env var or `wandb login`\n- `git` on PATH\n\n## Installation / usage\n\nCodex command shape from the repo root:\n\n```bash\n# Clone and install deps (no pip install needed — it's a script)\ngit clone https://github.com/jc1122/metaopt-preflight\ncd metaopt-preflight\npip install -r requirements.txt\n\n# Run preflight from the metaopt-preflight repo root:\npython3 -m scripts.run_preflight \\\n  --campaign /absolute/path/to/ml_metaopt_campaign.yaml \\\n  --cwd /absolute/path/to/project-root\n\n# Direct script form from the repo root, or with an absolute script path:\npython3 scripts/run_preflight.py \\\n  --campaign /absolute/path/to/ml_metaopt_campaign.yaml \\\n  --cwd /absolute/path/to/project-root\n```\n\nFor Codex, always pass both flags explicitly with absolute paths. The CLI\nrejects a relative `--campaign` and rejects a relative `--cwd` when `--cwd` is\nprovided. If `--cwd` is omitted, the current process directory is used; reserve\nthat form for local shell use where the working directory is already known.\n\nThe module form (`python3 -m scripts.run_preflight`) must be run from the\n`metaopt-preflight` repo root or with an equivalent `PYTHONPATH`. The direct\nscript form can be called by absolute script path from any shell cwd.\n\n`--campaign` points to the campaign YAML to parse. `--cwd` points to the target\nproject root where preflight evaluates readiness, may scaffold `.ml-metaopt/`,\nand writes `.ml-metaopt/preflight-readiness.json`.\n\n### CLI flags\n\n| Flag | Required | Default | Description |\n|------|----------|---------|-------------|\n| `--campaign` | Yes | — | Path to the campaign YAML file that preflight parses |\n| `--cwd` | No | current process directory | Project root directory where readiness is evaluated and the artifact is written; if provided, it must be absolute |\n\n## Exit codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | READY — proceed with `ml-metaoptimization` |\n| 1 | FAILED — fix reported issues and re-run; if the readiness artifact cannot be written, the error is printed to stderr |\n| 2 | Usage/input error — bad args, missing campaign file, or malformed YAML |\n\nExit code `2` returns before the Emit phase, so no readiness artifact is\nwritten for usage/input failures.\n\n## What gets checked\n\n### Repository checks (R1–R9)\n\n| Check | Description | Scaffoldable |\n|-------|-------------|:------------:|\n| R1 | `.ml-metaopt/` directory exists | Yes |\n| R2 | `.gitignore` contains `.ml-metaopt/` entry | Yes |\n| R3 | `.ml-metaopt/handoffs/` subdir exists | Yes |\n| R4 | `.ml-metaopt/worker-results/` subdir exists | Yes |\n| R5 | `.ml-metaopt/tasks/` and `executor-events/` exist | Yes |\n| R6 | All `artifacts/` subdirs exist (`code/`, `data/`, `manifests/`, `patches/`) | Yes |\n| R7 | `project.smoke_test_command` is a non-empty string | No |\n| R8 | Required top-level campaign YAML keys present | No |\n| R9 | `project.repo` is a non-empty string | No |\n\n### Backend checks (advisory — not auto-fixed)\n\n| Check | Description |\n|-------|-------------|\n| `skypilot_installed` | `sky` CLI on PATH |\n| `vast_configured` | Vast.ai enabled in SkyPilot (`sky check`) |\n| `wandb_credentials` | `WANDB_API_KEY` set or `~/.netrc` has `api.wandb.ai` |\n| `repo_access` | `git ls-remote` succeeds against `project.repo` |\n| `smoke_test_command_nonempty` | `project.smoke_test_command` is non-empty (warning) |\n\n## Filesystem effects and bootstrap\n\nRepo bootstrap mutations (B1–B3) are auto-applied for fixable issues:\n\n| ID | Trigger | Action |\n|----|---------|--------|\n| B1 | R1 fails | `mkdir -p .ml-metaopt` |\n| B2 | R3–R6 fail | `mkdir -p` all 8 required subdirectories |\n| B3 | R2 fails | Append `.ml-metaopt/` to `.gitignore` |\n\nCurrent executable behavior keeps backend bootstrap advisory only: backend\nfailures produce remediation guidance in the emitted result, but the CLI does\nnot auto-install packages, mutate credentials, create remote backend resources,\nor start runtime workers.\n\nPreflight may:\n\n- create `.ml-metaopt/` scaffolding under `--cwd`\n- create or append the root `.gitignore` entry for `.ml-metaopt/`\n- overwrite `.ml-metaopt/preflight-readiness.json` on each READY or FAILED run\n\nPreflight must not write `.ml-metaopt/state.json`, `AGENTS.md`, experiment\ncode, commits, or remote backend resources.\n\nAll supported mutations are idempotent. The latest emitted readiness artifact\non disk is always authoritative.\n\n## Output artifact\n\nWritten to `.ml-metaopt/preflight-readiness.json`:\n\n```json\n{\n  \"schema_version\": 1,\n  \"status\": \"READY\",\n  \"campaign_id\": \"my-campaign\",\n  \"campaign_identity_hash\": \"sha256:…\",\n  \"runtime_config_hash\": \"sha256:…\",\n  \"emitted_at\": \"2025-01-15T12:00:00Z\",\n  \"preflight_duration_seconds\": 4.2,\n  \"checks_summary\": { \"total\": 14, \"passed\": 12, \"failed\": 0, \"bootstrapped\": 2, \"warnings\": 0 },\n  \"failures\": [],\n  \"next_action\": \"proceed\",\n  \"diagnostics\": \"Created .ml-metaopt/ subtree.\"\n}\n```\n\nKey fields: `status` (`READY` | `FAILED`), `campaign_identity_hash`,\n`failures` (empty when READY), `next_action` (`proceed` or a short fix summary\nderived from the remaining failures).\n\n`checks_summary` counters:\n\n| Field | Meaning |\n|-------|---------|\n| `total` | Number of checks evaluated |\n| `passed` | Passed on initial evaluation |\n| `failed` | Still failing after bootstrap |\n| `bootstrapped` | Initially failed, fixed by bootstrap |\n| `warnings` | Advisory issues that don't block readiness |\n\nInvariant: `passed + failed + bootstrapped + warnings == total`.\n\nEvery preflight invocation that reaches Emit overwrites any previous\nartifact at the same path. There is no append log and no resume state.\n\n## Integration with ml-metaoptimization\n\nThe readiness artifact is the sole interface between the two projects.\n\n```\nmetaopt-preflight                     ml-metaoptimization\n─────────────────                     ────────────────────\n Gather → Evaluate → Bootstrap → Emit\n                                  │\n                                  ▼\n                          preflight-readiness.json\n                                  │\n                                  ▼\n                            LOAD_CAMPAIGN\n```\n\n- Re-run preflight whenever campaign config changes.\n- `LOAD_CAMPAIGN` computes its own `campaign_identity_hash` and compares it\n  to the artifact. If they don't match → `BLOCKED_CONFIG`.\n- A `FAILED` artifact with matching hashes still blocks — the environment\n  isn't ready.\n- `runtime_config_hash` is emitted for forward compatibility, but v4 validates\n  only `campaign_identity_hash` at campaign entry.\n\n## Validation\n\n```bash\npython3 -m pytest -q\n# or: python -m unittest discover -s tests -p 'test_*.py'\n```\n\n## References\n\n- [SKILL.md](SKILL.md) — full skill contract (input/output, rules, phases)\n- [references/boundary.md](references/boundary.md) — ownership boundary and lifecycle\n- [references/readiness-artifact.md](references/readiness-artifact.md) — artifact schema and freshness rules\n- [references/backend-setup.md](references/backend-setup.md) — backend readiness checks and bootstrap\n- [references/repo-setup.md](references/repo-setup.md) — repo structure checks and scaffolding mutations\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjc1122%2Fmetaopt-preflight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjc1122%2Fmetaopt-preflight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjc1122%2Fmetaopt-preflight/lists"}