docs: consolidate agent execution and custody
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
CI Smoke / container-smoke (push) Successful in 2s
ci / test (push) Successful in 52s

This commit is contained in:
tegwick 2026-08-20 22:43:55 +02:00
parent 6ed5708c21
commit d691135c4a
19 changed files with 372 additions and 64 deletions

View file

@ -37,14 +37,36 @@ end-to-end flow:
```
activity-core cron
→ context resolver (roster ∩ repos with schedule.yml)
task per (repo, agent)
coding-agent session runs `kaizen-agentic schedule prepare <agent>`
durable work per (repo, agent)
governed runner executes `kaizen-agentic schedule prepare <agent>`
→ session executes the agent instructions in that repo
```
kaizen-agentic's responsibilities are exactly two: **declare** the schedule
(`.kaizen/schedule.yml`) and **prepare** an orientation bundle for a run. It
does **not** fire cron, create tasks, or invoke Claude.
does **not** fire cron, own the durable work queue, or invoke an LLM.
### Current runtime realization (2026-08-20)
The initial contract above remains valid, but the generic word “task” now has a
specific durable implementation:
```
activity-core Temporal schedule/event
→ rule evaluation and eligibility
→ unique, idempotent ops_run with lease/retry state
→ rein-aharness claim loop
→ agent-session approach and governed runtime/profile resolution
→ kaizen-agentic schedule prepare <agent>
→ bounded coding-agent session
→ ops_run result + State Hub progress + .kaizen metrics/artifact evidence
```
`activity-core` owns schedule and durable work state. `rein-aharness` owns
claiming, execution policy, credential routing, runtime selection, and bounded
session operation. Kaizen Agentic continues to own declaration, agent craft,
preparation, and improvement evidence. A human-started coding-agent session
remains a supported execution mode and reference smoke path.
### 1. Schedule manifest — `.kaizen/schedule.yml`
@ -123,10 +145,13 @@ kaizen-agentic schedule prepare <agent> [--target PATH] [--format markdown|json]
## Boundaries
- **No scheduling code** in kaizen-agentic. Cron and task creation belong to
activity-core; the roster query belongs to state-hub.
- **No scheduling or durable-queue code** in kaizen-agentic. Temporal schedules,
rule evaluation, and `ops_run` state belong to activity-core; the roster query
belongs to State Hub.
- **No LLM invocation.** `prepare` produces a runner-agnostic bundle; a human or
automated coding-agent session executes it.
rein-aharness-governed coding-agent session executes it.
- **No runtime authority or credentials.** Those remain with rein-aharness and
the ecosystem credential/authorization owners.
- **State-hub schema changes** (roster opt-in flag) are designed here but
implemented in `the-custodian` (repo boundary).
@ -134,7 +159,7 @@ kaizen-agentic schedule prepare <agent> [--target PATH] [--format markdown|json]
- Operators declare per-repo schedules and a fleet roster without tribal
knowledge.
- activity-core can fire recurring tasks referencing `schedule prepare`.
- activity-core can fire recurring durable work referencing `schedule prepare`.
- A scheduled session opens with full orientation (prompt + memory + metrics).
- The existing `weekly-metrics-optimize` definition (ADR-004 / WP-0004) remains
complementary; an `optimization` agent run may chain `schedule prepare