110 lines
3.7 KiB
Markdown
110 lines
3.7 KiB
Markdown
# Resolver Spec: `discover_kaizen_scheduled_repos`
|
|
|
|
**Status:** implemented in activity-core (`context_resolvers/kaizen.py`). This doc
|
|
is the contract an activity-core implementer needs to add the context resolver
|
|
that feeds the scheduled-agent ActivityDefinitions (ADR-005).
|
|
|
|
## Purpose
|
|
|
|
Given the fleet roster and per-repo schedule manifests, emit one entry per
|
|
`(repo, agent)` that is due to run, so ActivityDefinitions can `for_each` over
|
|
the result.
|
|
|
|
## Signature
|
|
|
|
```
|
|
discover_kaizen_scheduled_repos(
|
|
domain: str | None = None, # optional scope filter, e.g. "custodian"
|
|
cadence: str | None = None, # optional: "daily" | "weekly" | "monthly"
|
|
now: datetime | None = None, # injection point for testing
|
|
) -> { "scheduled_runs": list[ScheduledRun] }
|
|
```
|
|
|
|
Bound in a definition as:
|
|
|
|
```yaml
|
|
context_sources:
|
|
- type: resolver
|
|
query: discover_kaizen_scheduled_repos
|
|
params:
|
|
domain: custodian
|
|
cadence: weekly
|
|
bind_to: context.scheduled_runs
|
|
```
|
|
|
|
## Inputs (sources, in order)
|
|
|
|
1. **State Hub** `GET /repos/` (optionally filtered by `domain` and, when the v2
|
|
flag lands, `kaizen_schedule_enabled=true`). Yields `slug`, `host_paths`,
|
|
`domain`.
|
|
2. **Repo checkout** at `host_paths[<runner-host>]`: read
|
|
`.kaizen/schedule.yml`. Skip repos without the file.
|
|
3. **Validation**: run the equivalent of `kaizen-agentic schedule validate`.
|
|
Skip (and log) repos whose schedule is invalid — never emit a bad entry.
|
|
|
|
## Output shape
|
|
|
|
```json
|
|
{
|
|
"scheduled_runs": [
|
|
{
|
|
"repo": "kaizen-agentic",
|
|
"root": "/home/worsch/kaizen-agentic",
|
|
"agent": "coach",
|
|
"cadence": "weekly",
|
|
"cron": "0 9 * * 1",
|
|
"timezone": "Europe/Berlin",
|
|
"enabled": true,
|
|
"prepare_command": "kaizen-agentic schedule prepare coach --target /home/worsch/kaizen-agentic"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### `ScheduledRun` fields
|
|
|
|
| Field | Source | Notes |
|
|
|-------|--------|-------|
|
|
| `repo` | hub `slug` | becomes `target_repo` on the created task |
|
|
| `root` | `host_paths[<host>]` | absolute checkout path on the runner |
|
|
| `agent` | schedule.yml key | |
|
|
| `cadence` | schedule.yml | |
|
|
| `cron` | schedule.yml or definition default | per-repo override when present |
|
|
| `timezone` | schedule.yml or definition default | |
|
|
| `enabled` | schedule.yml (`true` only emitted) | disabled entries are filtered out |
|
|
| `prepare_command` | derived | exact CLI the task should run |
|
|
|
|
## Filtering rules
|
|
|
|
- Emit only entries with `enabled: true`.
|
|
- When `cadence` param is set, emit only matching entries (lets each cron-bound
|
|
definition select its own cadence slice).
|
|
- When `cron` is present on the entry, it is the authoritative per-repo time;
|
|
otherwise the definition's cron applies.
|
|
|
|
## Errors
|
|
|
|
| Condition | Behavior |
|
|
|-----------|----------|
|
|
| Repo unreachable / path missing on host | Skip + log `repo_unreachable` |
|
|
| `.kaizen/schedule.yml` absent | Skip silently (not opted in) |
|
|
| schedule.yml invalid | Skip + log `schedule_invalid` with validation errors |
|
|
| Hub unreachable | Fail the resolver run (no roster = no safe output) |
|
|
|
|
The resolver must be **idempotent** and **side-effect free**: it reads, it does
|
|
not write. Task creation happens in the ActivityDefinition rule, not here.
|
|
|
|
## Test fixtures
|
|
|
|
- A repo with valid `.kaizen/schedule.yml` (coach enabled) → one entry.
|
|
- A repo with the file but coach `enabled: false` → no entry.
|
|
- A repo without the file → no entry.
|
|
- A repo with an invalid schedule → no entry + logged error.
|
|
|
|
## Related
|
|
|
|
- [state-hub-roster-fields.md](state-hub-roster-fields.md)
|
|
- [schedule-schema.md](schedule-schema.md)
|
|
- [activity-definitions/weekly-coach-orientation.md](activity-definitions/weekly-coach-orientation.md)
|
|
- [ADR-005](../adr/ADR-005-scheduled-agent-execution.md)
|