AGENTS.md@infrastructure/orchestration git:20260828.573bbdbA

Immutable. This exact content is served forever at /api/v1/blob/67f0de9b0ded7927.

# Orchestration Package

## Purpose

This package hosts the logic that historically lived almost entirely in `run.sh` and `secure_run.sh`. The shell scripts are thin: they bootstrap `uv` / `.venv` and delegate here via `python -m infrastructure.orchestration`.

This package coordinates existing Layer-1 modules (`infrastructure.core.pipeline`, `infrastructure.project.discovery`, `infrastructure.steganography`, …). It does **not** re-implement DAG stages.

## Files

| File | Role |
| --- | --- |
| `cli.py` | Backward-compatible facade retaining `build_parser()` and `main()`. |
| `parser.py` | Pure argparse construction for non-interactive commands. |
| `commands.py` | Non-interactive command handlers and dispatch table. |
| `interactive.py` | TTY-only menu loop and project prompting. |
| `discovery.py` | `validate_project_slug`, `resolve_project_info`, `select_project_interactive`, `discover_qualified_names` — one `discover_projects()` pass is shared by slug validation and lookup (`validate_project_slug(..., projects=)`). When `writer` is set, the picker lists projects and prints `Choice [index / a=all / q=quit]: ` before reading input. |
| `menu.py` | `MENU_OPTIONS`, `render_menu`, `_menu_row` — deterministic, ANSI-free menu text. Framing and section rules use ASCII (`+`, `=`, `-`, `|`) for TTY compatibility; option rows stay column-aligned. [`tests/infra_tests/orchestration/test_menu.py`](../../tests/infra_tests/orchestration/test_menu.py) asserts stable legend substrings and each `_menu_row` line. Used by `_interactive` and the `menu` subcommand. |
| `pipeline_runner.py` | `PipelineRunner` — thin adapter over `PipelineExecutor`. |
| `stage_logger.py` | `setup_stage_log`, `stage_log_path` — append-only banners under project log paths. |
| `secure_run.py` | `run_secure_pipeline` — pipeline + steganography post-processing. |
| `link_sync.py` | Sidecar link-sync hook registry: `register_link_sync` / `registered_link_sync_hooks`, `maybe_sync_all_links`, and `print_link_sync_result(s)`. Registers the projects/fonds/rules/tools sync hooks (each skipped via its own `*_SKIP` env var). |

## Contracts

- **No pipeline stage logic.** Stage scripts remain under [`scripts/`](../../scripts/).
- **Interactive menu keys `0`–`7`** dispatch single stages via [`stage_registry.MENU_KEY_TO_STAGE`](../core/pipeline/stage_registry.py) → [`execute_single_stage()`](../core/pipeline/single_stage.py) (direct subprocess to `scripts/NN_*.py`); they do not shell out to `execute_pipeline.py --stage`.
- **Slug validation** rejects traversal (`..`), NUL bytes, `-` prefixes, unknown project names from `discover_projects()`.
- **Qualified exemplar paths** resolve as `templates/<name>` and `active/<name>` under `projects/` (see [`docs/_generated/active_projects.md`](../../docs/_generated/active_projects.md)). Live counts link to [`docs/_generated/COUNTS.md`](../../docs/_generated/COUNTS.md).
- **Tests:** [`tests/infra_tests/orchestration/`](../../tests/infra_tests/orchestration/).

## See also

- [`README.md`](README.md)
- [`SKILL.md`](SKILL.md)