Refactor recipe CI into language-agnostic structure workflow (+ oauth recipe)

[happyhuman]

Summary

Three things in one PR, main change first:

1. CI refactor: split recipe validation into a new language-agnostic validate-recipe-structure.yml and a slimmed-down Python-only python-validate-recipe.yml. Required-files matrix moves into .github/policy.yml as declarative config. Preps the tree for multi-language recipes (java/go/kotlin/typescript) and the planned skills/ folder.
2. New recipe: core/python/oauth-user-consent-flow — an ADK agent deployed on Agent Runtime with OAuth 2.0, reads Google Drive files on behalf of authenticated users.
3. Docs pass: every workflow under .github/workflows/ now has a 20–30 word summary comment right after name:.

The CI refactor (the main change)

Before: python-validate-recipe.yml owned every check for Python recipes — structural (folder name, size, file count, required files, manifest schema) and Python-specific (env-var extraction, [project] metadata, no-local-ruff, model-name notice). 666 lines of bash. Adding a new language would have meant duplicating most of it.

After:

• validate-recipe-structure.yml (new) — language-agnostic; runs manifest presence + schema, folder name, folder size + file count, and the required-files matrix for every recipe under core/, contrib/, and skills/.
• python-validate-recipe.yml (kept, shrunk 666 → 305 lines) — Python-only: .env.example env-key notice, AST-based env-var extraction, no-local-ruff-config, [project] metadata (name matches folder, requires-python floor, description matches manifest), hardcoded-model-name notice.
• validate-manifest.yml (deleted) — absorbed into the structure workflow.

Language detection now uses manifest.language as the single source of truth; path convention is not consulted by the structural checker.

The required-files matrix

Now declarative in .github/policy.yml:

required_files:
  always:
    - README.md
  by_root:
    core:    [AGENTS.md]        # broadened from core/python/* to ALL core/*
    contrib: []
    skills:  [SKILL.md]         # scaffolded ahead of the folder existing
  by_language:
    python:  [pyproject.toml, uv.lock, .env.example, tests/test_runnability.py]
    java:    []                 # placeholders for languages that don't have recipes yet
    go:      []
    kotlin:  []
    typescript: []

Adding a language or a folder rule (e.g. SKILL.md for skills/) is a one-line YAML edit — no workflow diff, no bash surgery.

New shared tooling

• tools/validate_structure.py — the structural checker; runnable locally via uv run validate structure [<recipe>] or uv run validate (which now runs both manifest + structure).
• tools/affected_recipes.py — shared "changed files → recipe directories" mapper. Handles flat (<root>/<recipe>) and language-namespaced (<root>/<language>/<recipe>) layouts. Supports --language <lang> filter with path-first semantics (namespaced dirs authoritative, flat recipes read manifest.language). Both existing workflows now use this instead of duplicating the mapping in bash.
• 76 new tests across four files (127 total for tools/).

Adding a new language later

For java/go/kotlin/typescript, the recipe author only needs to:

1. Add one line under required_files.by_language in policy.yml.
2. Ship a small <lang>-validate-recipe.yml for language-specific rules only.

Structural validation is already covered.

The new recipe

core/python/oauth-user-consent-flow — production-ready ADK agent, deploys to Agent Runtime, reads Google Drive files with OAuth 2.0 consent. Works both locally via ADK Web UI and in production via Gemini Enterprise. Comes with unit + integration + eval tests and a runnability test.

Workflow docs pass

Every workflow file under .github/workflows/ now has a 20–30 word summary comment directly after name:. The two workflows I extensively touched had detailed 120-word comments compressed to the same style, and all other workflows got one added (they had none before). Consistent, greppable, and cheap to keep updated.

Docs

docs/recipe-guidelines.md restructured:

• Required-files split into three tables (every recipe / by-folder / by-language) matching the new matrix.
• Added skills/ and AGENTS.md (previously omitted).
• Documented the new uv run validate structure and uv run validate commands.
• Added a "What CI runs" section explaining the two-workflow architecture.

Verified

• All 127 tools/ tests pass locally.
• All 5 committed recipes pass both uv run validate manifest and uv run validate structure.
• Broken-recipe smoke test emits one line per problem (no double-reporting of missing manifest.yaml).
• End-to-end simulation of a PR-style git diff → affected_recipes.py → per-recipe validation works on real recipe paths.
• Both workflow YAMLs parse cleanly.

No behavioural regression

The AGENTS.md broadening (previously core/python/* only, now all core/*) is a no-op today because both existing flat core/ recipes already carry AGENTS.md. Future core/java/foo/ etc. will need it too — this is intentional and now documented in policy.yml.