docs: bind WP-0006 State Hub task IDs after fix-consistency

Inject hub task UUIDs from consistency sync; normalize workplan frontmatter.
docs: add WP-0006 scheduled agent execution workplan
2026-06-17 01:13:54 +02:00 · 2026-06-17 01:13:10 +02:00 · 2026-06-17 01:07:12 +02:00 · 2026-06-17 01:04:39 +02:00 · 2026-06-17 01:02:08 +02:00
7 changed files with 685 additions and 15 deletions
--- a/.custodian-brief.md
+++ b/.custodian-brief.md
@@ -0,0 +1,18 @@
+<!-- custodian-brief: generated by fix-consistency — do not edit manually -->
+# Custodian Brief — kaizen-agentic
+
+**Domain:** custodian
+**Last synced:** 2026-06-16 23:04 UTC
+**State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
+
+## Active Workstreams
+
+*(none — repo may need first-session setup)*
+
+---
+## MCP Orientation (when available)
+
+If the state-hub MCP server is reachable, call:
+`get_domain_summary("custodian")`
+This provides richer cross-domain context.
+If the MCP call fails, use this file as your orientation source.
--- a/SCOPE.md
+++ b/SCOPE.md
@@ -74,7 +74,7 @@ This repo is the canonical home for the **KaizenAgentic** operating model (`INTE
 - Implementation: 20 agents, full CLI (`metrics`, `memory`, `feedback`), agency memory + ADR-004 metrics + optimizer wiring
 - Stability: CLI stable (Click workaround in place); Gitea CI on main; publish workflow on `v*` tags
 - Usage: internal dev projects and Custodian MCP hub-wide; pip install via Gitea extra index
- Active work: **WP-0005** (adoption polish, fleet parity, publish verification → v1.2.0)
+- Active work: **WP-0006** (scheduled agent execution via activity-core → v1.3.0)

 ---

--- a/TODO.md
+++ b/TODO.md
@@ -10,18 +10,14 @@ The structure organizes **future tasks** by their impact, just as a changelog or

 ## [Unreleased] - *Active Vibe-Coding State* 💡

-Tasks in workplan: `workplans/kaizen-agentic-WP-0005-adoption-parity.md` (v1.2.0)
+Tasks in workplan: `workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md` (v1.3.0)

 ### To Add
-* **Gitea publish pipeline verification** — secrets + workflow smoke test
-* **`make agents-sync-package`** — keep `data/agents/` aligned with `agents/`
-* **Install doc sweep** — HELLO_WORLD, CLI_CHEAT_SHEET, AGENT_DISTRIBUTION
+* **ADR-005 + `.kaizen/schedule.yml`** — scheduled agent execution contract
+* **`kaizen-agentic schedule`** — validate, init, prepare, list
+* **activity-core definitions** — weekly coach + optimization on preselected repos

-### To Refactor
-* **CI lint gate** — flake8 on `src/` in Gitea Actions
-* **Makefile install hints** — point at Gitea registry or dev install
-
-### Deferred to WP-0006 (v1.3.0)
+### Deferred to WP-0007 (v1.3.0+)
 * Interactive agent selection wizard
 * Agent template schema validation in `validate`
 * Documentation generation from agent metadata
--- a/workplans/kaizen-agentic-WP-0003-measurement-loop.md
+++ b/workplans/kaizen-agentic-WP-0003-measurement-loop.md
@@ -9,7 +9,104 @@ owner: kaizen-agentic
 topic_slug: custodian
 state_hub_workstream_id: 36252a45-f360-4496-bf77-17b5dfb02767
 created: "2026-06-16"
-updated: "2026-06-18"
+updated: "2026-06-17"
+tasks:
+  - id: T01
+    title: Write ADR-004 project metrics convention
+    status: done
+    state_hub_task_id: 4e7b0fd2-38c0-46aa-84a7-bb18366b8c7c
+  - id: T02
+    title: Implement MetricsStore in metrics.py
+    status: done
+    state_hub_task_id: eeaa99c7-d7a7-403b-a013-364cba45a663
+  - id: T03
+    title: Add memory init hook to scaffold metrics directory
+    status: done
+    state_hub_task_id: 247c097f-de89-4383-930c-35ee66de9b36
+  - id: T04
+    title: Unit tests for MetricsStore
+    status: done
+    state_hub_task_id: 3aa14026-6ee3-4384-b409-11300c1302f0
+  - id: T05
+    title: Implement metrics CLI command group
+    status: done
+    state_hub_task_id: 6b505d29-7d2e-44a2-a4b7-1fe82884390c
+  - id: T06
+    title: Integrate metrics record into session-close template
+    status: done
+    state_hub_task_id: 84f2a357-f2dd-4fc7-96b6-a4e80d5467a7
+  - id: T07
+    title: CLI tests for metrics commands
+    status: done
+    state_hub_task_id: 8e9ee64b-b7c4-4dff-ac6e-988fd47ef95d
+  - id: T08
+    title: Update CLI cheat sheet and agency-framework with metrics
+    status: done
+    state_hub_task_id: 4c41e0db-d5d8-4a1b-b346-06ad004edf4a
+  - id: T09
+    title: Add OptimizationLoop.from_metrics_store factory
+    status: done
+    state_hub_task_id: 0b374439-6eca-4754-8e15-2a7eece0cd27
+  - id: T10
+    title: Implement kaizen-agentic metrics optimize command
+    status: done
+    state_hub_task_id: db87a09b-0252-495c-a771-a43b4b98f820
+  - id: T11
+    title: Consolidate optimization meta-agent definitions
+    status: done
+    state_hub_task_id: 73cb7d73-6fc6-42a9-97aa-d33cdf9ee363
+  - id: T12
+    title: Update optimization agent session protocol
+    status: done
+    state_hub_task_id: c127eca7-7394-42db-ba5e-721aef0ccb76
+  - id: T13
+    title: Unit and integration tests for optimizer recommendations
+    status: done
+    state_hub_task_id: f208dc9f-cdf7-47e3-9c03-09097e46eee9
+  - id: T14
+    title: Extend memory brief with metrics summary
+    status: done
+    state_hub_task_id: d01f969c-bbb1-4eca-a4f1-d79d5c867b35
+  - id: T15
+    title: Extend agent-coach.md for metrics context
+    status: done
+    state_hub_task_id: 67f791a4-fced-4986-a331-7eb4ea47fe6e
+  - id: T16
+    title: E2e test memory brief with metrics sections
+    status: done
+    state_hub_task_id: 1fb89b54-8bd2-40bf-9a71-04693cb9f695
+  - id: T17
+    title: Add metrics section to agent-tdd-workflow.md
+    status: done
+    state_hub_task_id: 1d471a7a-9a98-4805-903e-b4a2b8153717
+  - id: T18
+    title: Add session-close metrics record step to tdd-workflow
+    status: done
+    state_hub_task_id: abb387f1-86ce-4b9b-a516-2d4efb6aca4c
+  - id: T19
+    title: Document tdd-workflow pilot in wiki/AboutKaizenAgents.md
+    status: done
+    state_hub_task_id: 67fbc26e-a57d-4133-96e6-3d2cdbd10dc0
+  - id: T20
+    title: E2e test full tdd-workflow measure-analyse-orient loop
+    status: done
+    state_hub_task_id: fbdd7c8b-e122-48d9-8c8f-de9f82d025e3
+  - id: T21
+    title: Sync 4 missing agents into packaged data/
+    status: done
+    state_hub_task_id: 9662bcec-34fe-451b-b61f-5d11b9574576
+  - id: T22
+    title: Update README orientation links to INTENT and wiki
+    status: done
+    state_hub_task_id: 422aae43-5697-4a00-86e9-1569baf09422
+  - id: T23
+    title: Update architecture.md agent table
+    status: done
+    state_hub_task_id: ba6b3411-d330-4a58-8cd0-62b4fbef8c5f
+  - id: T24
+    title: CHANGELOG entry for metrics convention and CLI
+    status: done
+    state_hub_task_id: 748be9f3-f6ac-4f26-a844-6330268935b6
 ---

 # KAIZEN-WP-0003 — Measurement Loop: Metrics Convention, Collection, and Optimizer Integration
@@ -249,6 +346,23 @@ A reader of `INTENT.md` can point to this repo and say:

 ---

+## Completion
+
+**Shipped:** v1.1.0 (2026-06-18); measurement loop operational through v1.2.0.
+
+| Milestone | Detail |
+|-----------|--------|
+| ADR-004 | Project metrics convention (`.kaizen/metrics/`) |
+| CLI | `metrics record`, `show`, `list`, `export`, `optimize` |
+| Coach bridge | `memory brief` includes `## Performance Summary` |
+| Pilot | `tdd-workflow` reference in `wiki/AboutKaizenAgents.md` |
+| Tests | `test_metrics*.py`, `test_optimization_metrics.py`, e2e agency tests pass |
+
+All 24 tasks complete. Fleet-wide template conformance and scheduled optimizer runs
+remain out of scope (future workplans).
+
+---
+
 ## State Hub Task IDs

 | Code | UUID |
@@ -286,4 +400,4 @@ A reader of `INTENT.md` can point to this repo and say:

 - Retention default: 180 days (per `wiki/AgentKaizenOptimizer.md`); override via project config in a later iteration
 - WP-0001 T04 (telemetry) should consume ADR-004 schema rather than inventing a parallel format
- `OptimizationLoop` threshold constants (30s execution, 0.8 success rate) are starting points; expose in config later
+- `OptimizationLoop` threshold constants (30s execution, 0.8 success rate) are starting points; expose in config later
--- a/workplans/kaizen-agentic-WP-0004-ecosystem-integration.md
+++ b/workplans/kaizen-agentic-WP-0004-ecosystem-integration.md
@@ -9,7 +9,84 @@ owner: kaizen-agentic
 topic_slug: custodian
 state_hub_workstream_id: 76be7294-e201-4074-91c0-6421992470fe
 created: "2026-06-16"
-updated: "2026-06-18"
+updated: "2026-06-17"
+tasks:
+  - id: T01
+    title: Document Helix Forge correlation contract cross-repo
+    status: done
+    state_hub_task_id: f365d19e-9619-4453-bebf-f1fd596b1bd1
+  - id: T02
+    title: Add HELIX_SESSION_UID to metrics record
+    status: done
+    state_hub_task_id: e7f47683-5957-49db-bcbd-3aa47f44a073
+  - id: T03
+    title: Add kaizen-agentic metrics correlate command stub
+    status: done
+    state_hub_task_id: 6ef8ba99-7d0c-44f4-835d-7a66e9d55984
+  - id: T04
+    title: Integration test for helix_session_uid correlation
+    status: done
+    state_hub_task_id: 9875422c-a54b-40f1-a444-6b485a9e57d6
+  - id: T05
+    title: Update EcosystemIntegration.md with worked example
+    status: done
+    state_hub_task_id: 0dc33d13-0e0b-4336-a7ad-371fc533b823
+  - id: T06
+    title: Draft weekly metrics optimize ActivityDefinition
+    status: done
+    state_hub_task_id: dbaa5f46-f66a-4a74-b4a0-97978e47d1c3
+  - id: T07
+    title: Draft post-install metrics scaffold ActivityDefinition
+    status: done
+    state_hub_task_id: 161a264a-8f70-4e37-a854-bd5a76a0e54b
+  - id: T08
+    title: Draft low success_rate review ActivityDefinition
+    status: done
+    state_hub_task_id: 3b58ad38-839c-436a-8d97-ef5a8f9beefe
+  - id: T09
+    title: Document activity-core triggers in INTEGRATION_PATTERNS.md
+    status: done
+    state_hub_task_id: a004b60f-4e8f-4881-b088-229ac9ab242f
+  - id: T10
+    title: Smoke test activity-core activation
+    status: done
+    state_hub_task_id: 84866bf1-5830-470d-87a5-9786222332c2
+  - id: T11
+    title: Define optimizer artifact package manifest
+    status: done
+    state_hub_task_id: 033a19db-fbd2-411f-9d2e-779d210400d4
+  - id: T12
+    title: Add kaizen-agentic metrics publish command
+    status: done
+    state_hub_task_id: 54517f2b-23e3-433b-a483-c59227625dbc
+  - id: T13
+    title: Map raw-evidence retention class in publish manifest
+    status: done
+    state_hub_task_id: 3b378789-a761-4472-b072-a346541be239
+  - id: T14
+    title: Integration test artifact-store publish
+    status: done
+    state_hub_task_id: a3566713-db58-4519-b9c4-5003421c1f1e
+  - id: T15
+    title: Document publish workflow in agency-framework.md
+    status: done
+    state_hub_task_id: 5d8255aa-fd7a-4fe6-bce2-3a176f954c7f
+  - id: T16
+    title: Map KaizenAgentTemplate to info-tech-canon profile outline
+    status: done
+    state_hub_task_id: 852c9cbf-0b0c-4f23-8594-905ca280c268
+  - id: T17
+    title: Draft info-tech-canon agent brief for tdd-workflow
+    status: done
+    state_hub_task_id: 62e05097-9033-401d-bbe0-d5d773da50fe
+  - id: T18
+    title: Spike kontextual-engine wiki ingestion manifest
+    status: done
+    state_hub_task_id: cd6962c7-aaed-4d7d-81de-37c0e3ed715e
+  - id: T19
+    title: Update ecosystem assessment with Part 4 outcomes
+    status: done
+    state_hub_task_id: 2c1f66f5-e6ab-4e19-88ca-818acb15a706
 ---

 # KAIZEN-WP-0004 — Ecosystem Integration: Helix Forge, activity-core, and artifact-store
@@ -154,6 +231,21 @@ Estimated effort: 3–5 sessions after WP-0003 Part 3.

 ---

+## Completion
+
+**Shipped:** v1.1.0–v1.2.0 ecosystem integration layer.
+
+| Part | Outcome |
+|------|---------|
+| 1 Helix | `HELIX_SESSION_UID` on `metrics record`, `metrics correlate`, bidirectional docs |
+| 2 activity-core | Three ActivityDefinitions under `docs/integrations/activity-definitions/` |
+| 3 artifact-store | `metrics publish` with `raw-evidence` retention manifest |
+| 4 Canon/knowledge | Design docs for info-tech-canon and kontextual-engine (no runtime deps) |
+
+All 19 tasks complete. Reciprocal Helix link verified in WP-0005 T16.
+
+---
+
 ## State Hub Task IDs

 | Code | UUID |
@@ -187,4 +279,4 @@ Estimated effort: 3–5 sessions after WP-0003 Part 3.
 - ADR-004 Helix Forge correlation section is the authoritative field mapping
 - WP-0001 T04 (telemetry) should evaluate tele-mcp as adapter candidate
 - activity-core ActivityDefinitions live in activity-core repo per ACT-ADR-002/003;
-  kaizen-agentic commits reference copies or links under `docs/integrations/`
+  kaizen-agentic commits reference copies or links under `docs/integrations/`
--- a/workplans/kaizen-agentic-WP-0005-adoption-parity.md
+++ b/workplans/kaizen-agentic-WP-0005-adoption-parity.md
@@ -9,7 +9,72 @@ owner: kaizen-agentic
 topic_slug: custodian
 state_hub_workstream_id: 88c7b3e6-be98-480c-b47b-936e74a1a31b
 created: "2026-06-16"
-updated: "2026-06-16"
+updated: "2026-06-17"
+tasks:
+  - id: T01
+    title: Configure PACKAGE_USER and PACKAGE_TOKEN in Gitea
+    status: done
+    state_hub_task_id: 1fb6b04e-0854-4cc9-83c7-5abf85fe5bff
+  - id: T02
+    title: Smoke-test publish-python-package workflow
+    status: done
+    state_hub_task_id: bdb9e463-bdfb-405c-afc4-e93a7d58a18b
+  - id: T03
+    title: Add pre-tag release checklist to PACKAGE_RELEASE.md
+    status: done
+    state_hub_task_id: 6a2132e7-8b3f-4960-a5e8-85bad81e8b13
+  - id: T04
+    title: Update HELLO_WORLD_TUTORIAL.md Gitea install paths
+    status: done
+    state_hub_task_id: 553cba3a-dafa-483a-9200-70ac3f5eb2d7
+  - id: T05
+    title: Update CLI_CHEAT_SHEET.md Gitea install paths
+    status: done
+    state_hub_task_id: 7e6663a5-fedf-4b1c-acd9-6df6b43d8a12
+  - id: T06
+    title: Update AGENT_DISTRIBUTION.md Gitea install paths
+    status: done
+    state_hub_task_id: fe553788-357f-45c4-8400-f764f68c1cde
+  - id: T07
+    title: Update Makefile agents-* install fallback messages
+    status: done
+    state_hub_task_id: b131ff67-fe21-4d95-904b-6a0b916c5502
+  - id: T08
+    title: Cross-link CONTRIBUTING.md with PACKAGE_RELEASE.md
+    status: done
+    state_hub_task_id: 07dd4d25-250c-455c-8363-49269d2ee59f
+  - id: T09
+    title: Add make agents-sync-package target
+    status: done
+    state_hub_task_id: 7437cedd-5f7e-4c4d-9142-4f67470c9e52
+  - id: T10
+    title: Add release-check parity test agents vs data/agents
+    status: done
+    state_hub_task_id: ddbe2114-7a47-48fd-a145-b22dca2b581a
+  - id: T11
+    title: Refresh SCOPE.md agent-count notes
+    status: done
+    state_hub_task_id: 5417524f-03c0-40ed-a48b-a7906e6daf8f
+  - id: T12
+    title: Refresh TODO.md for v1.2.0
+    status: done
+    state_hub_task_id: 5cfad56c-2664-4b2d-b5f9-4792c958c9a2
+  - id: T13
+    title: Open CHANGELOG Unreleased for v1.2.0
+    status: done
+    state_hub_task_id: fbca9be4-3d2b-4989-baaf-97e6926bdc66
+  - id: T14
+    title: Add flake8 to Gitea CI workflow
+    status: done
+    state_hub_task_id: a6966cfa-ca59-4087-8989-2870dc69b13f
+  - id: T15
+    title: Document activity-core ActivityDefinition registration handoff
+    status: done
+    state_hub_task_id: fbf3f1a8-4818-473e-ae0d-cd80118e5319
+  - id: T16
+    title: Verify bidirectional Helix correlation doc link
+    status: done
+    state_hub_task_id: 37679ce7-dcb6-42a4-820d-cf8b32c2a248
 ---

 # KAIZEN-WP-0005 — Adoption Polish and Fleet Parity
@@ -154,6 +219,23 @@ Estimated effort: 2–4 sessions.

 ---

+## Completion
+
+**Shipped:** v1.2.0 on 2026-06-16
+
+| Milestone | Detail |
+|-----------|--------|
+| Release commit | `297afed` — adoption polish and publish pipeline |
+| Tag | `v1.2.0` pushed to Gitea |
+| Publish | Gitea Actions run **3044** — `kaizen_agentic-1.2.0` wheel + sdist uploaded |
+| Publish auth | `PACKAGE_USER=tegwick`, token from OpenBao `inter-hub-pkg-rep` |
+| Helix handoff | Reciprocal link in `agentic-resources/docs/DESIGN-session-memory.md` §11 |
+
+All 16 tasks complete. Deferred items (agent wizard, template validation, doc generation)
+tracked for **WP-0006** (v1.3.0).
+
+---
+
 ## State Hub Task IDs

 | Code | UUID |
--- a/workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md
+++ b/workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md
@@ -0,0 +1,368 @@
+---
+id: KAIZEN-WP-0006
+type: workplan
+title: "Scheduled Agent Execution via activity-core (v1.3.0)"
+domain: custodian
+repo: kaizen-agentic
+status: active
+owner: kaizen-agentic
+topic_slug: custodian
+state_hub_workstream_id: d4edb92b-526f-4ee4-8efe-a9fa84ab6dff
+depends_on:
+  - KAIZEN-WP-0003
+  - KAIZEN-WP-0004
+created: "2026-06-17"
+updated: "2026-06-17"
+tasks:
+- id: T01
+  state_hub_task_id: f513cf74-6e32-4dce-a3bc-2995f98a30de
+  status: todo
+  title: Write ADR-005 scheduled agent execution contract
+- id: T02
+  state_hub_task_id: dcb8d674-5472-4657-85bc-02ca9890fb92
+  status: todo
+  title: Define .kaizen/schedule.yml schema and example
+- id: T03
+  state_hub_task_id: 1f9a4959-d200-4d7b-8666-96472e23d820
+  status: todo
+  title: Add kaizen-agentic schedule validate command
+- id: T04
+  state_hub_task_id: 13ab4b76-ded2-4613-b8e2-15ab206d8c57
+  status: todo
+  title: Document fleet roster and repo opt-in in INTEGRATION_PATTERNS
+- id: T05
+  state_hub_task_id: 685b35f3-af20-483a-9136-150f5fff68dd
+  status: todo
+  title: Draft state-hub roster query design for activity-core resolver
+- id: T06
+  state_hub_task_id: 5f0a0859-3ff5-4ec8-b916-35486f045b2b
+  status: todo
+  title: Draft discover_kaizen_scheduled_repos context resolver spec
+- id: T07
+  state_hub_task_id: 2fd0f00c-5cf1-47bd-9c12-aee65bca5932
+  status: todo
+  title: Draft weekly-agent-run ActivityDefinition template
+- id: T08
+  state_hub_task_id: cc0565bc-ccd4-4739-9c7e-088adaa9834b
+  status: todo
+  title: Open activity-core handoff issue for resolver and definitions
+- id: T09
+  state_hub_task_id: 23aeff77-3429-438b-a395-5c7b5dc2824e
+  status: todo
+  title: Implement kaizen-agentic schedule prepare command
+- id: T10
+  state_hub_task_id: cba9685b-408f-4292-8169-9965e7ad5c5b
+  status: todo
+  title: Bundle memory brief metrics and agent prompt in prepare output
+- id: T11
+  state_hub_task_id: 7c1b049b-5566-4b5e-9d82-d9c29fab0c84
+  status: todo
+  title: Add schedule init scaffold for new repos
+- id: T12
+  state_hub_task_id: 80a8e98a-9146-4a58-8fd3-8c37f7893960
+  status: todo
+  title: Unit tests for schedule validate and prepare
+- id: T13
+  state_hub_task_id: 9aee6348-d5ad-4413-b01c-5588b07c8ede
+  status: todo
+  title: Pilot ActivityDefinition for weekly coach on custodian repos
+- id: T14
+  state_hub_task_id: 697e612b-7531-4329-82fb-b0423ba86904
+  status: todo
+  title: Pilot ActivityDefinition for weekly optimization review
+- id: T15
+  state_hub_task_id: 92db5130-2212-4780-ab8f-1de3adf6c6f8
+  status: todo
+  title: Smoke test end-to-end on two preselected repos
+- id: T16
+  state_hub_task_id: bbecdcbf-42b8-4b48-9f85-e4c10e4ff3ab
+  status: todo
+  title: Document operator enablement in PACKAGE_RELEASE and agency-framework
+- id: T17
+  state_hub_task_id: a9e91d4b-990a-457a-9591-d1243db5b386
+  status: todo
+  title: Emit kaizen.schedule.prepared event payload spec for activity-core
+- id: T18
+  state_hub_task_id: 73986472-bf19-4b13-af1b-6505ab944459
+  status: todo
+  title: Update wiki/EcosystemIntegration.md and CHANGELOG for v1.3.0
+---
+
+# KAIZEN-WP-0006 — Scheduled Agent Execution via activity-core
+
+**Status:** active
+**Owner:** kaizen-agentic
+**Repo:** kaizen-agentic
+**Target version:** 1.3.0
+**Depends on:** WP-0003 (metrics CLI), WP-0004 Part 2 (ActivityDefinition drafts)
+
+## Goal
+
+Enable kaizen agents to run **on a regular schedule** against **preselected repos**,
+orchestrated by **activity-core** and prepared by **kaizen-agentic** — without
+this repo owning Temporal workers or LLM runtime.
+
+Today, agents are markdown instruction sets invoked in coding-agent sessions.
+WP-0004 committed three metrics-focused ActivityDefinitions (`enabled: false`) but
+no general **agent dispatch** path, no **repo roster**, and no **per-repo schedule
+manifest**. This workplan closes that gap.
+
+### What “scheduled agent execution” means here
+
+```mermaid
+flowchart LR
+  AC[activity-core cron] --> CR[context resolver]
+  CR --> ROSTER[preselected repos]
+  ROSTER --> RULE[ActivityDefinition rule]
+  RULE --> TASK[hub task per repo+agent]
+  TASK --> PREP[kaizen-agentic schedule prepare]
+  PREP --> SESSION[coding-agent session]
+```
+
+1. **activity-core** fires on cron (or event).
+2. A **context resolver** returns repos from the preselected roster that have a
+   matching schedule entry and reachable `host_paths`.
+3. For each `(repo, agent)` pair, activity-core creates a **task** (State Hub /
+   issue-core) with labels and a `schedule prepare` command.
+4. A coding agent (human or automated session) runs `kaizen-agentic schedule prepare`
+   to assemble orientation: agent prompt, `memory brief`, metrics summary, repo
+   context — then executes the agent instructions in that repo.
+
+Kaizen-agentic does **not** invoke Claude directly; it **prepares** and **validates**
+the scheduled run contract.
+
+---
+
+## Background
+
+| Layer | WP-0004 state | WP-0006 adds |
+|-------|---------------|--------------|
+| activity-core | Three proposed definitions (metrics only) | Agent-run definitions + roster resolver |
+| kaizen-agentic | CLI for metrics/memory | `schedule` command group + `.kaizen/schedule.yml` |
+| state-hub | Registered repos + `host_paths` | Fleet roster opt-in + schedule metadata |
+| Execution | Manual session | Cron → task → prepared session bundle |
+
+**Prior WP-0006 placeholder** (agent wizard, template validation, doc generation)
+moves to **KAIZEN-WP-0007**.
+
+---
+
+## Part 1 — Schedule Contract (repo-local)
+
+Declare which agents run how often in each opted-in repo.
+
+### `.kaizen/schedule.yml` (draft shape)
+
+```yaml
+version: "1"
+timezone: Europe/Berlin
+agents:
+  coach:
+    cadence: weekly
+    cron: "0 9 * * 1"      # optional override; default from ActivityDefinition
+    enabled: true
+  optimization:
+    cadence: weekly
+    cron: "0 10 * * 1"
+    enabled: true
+  tdd-workflow:
+    cadence: monthly
+    enabled: false
+```
+
+### Tasks
+
+- [ ] T01 — Write ADR-005: scheduled agent execution (roster, schedule file, dispatch, boundaries)
+- [ ] T02 — Add `docs/integrations/schedule-schema.md` + example under `docs/examples/.kaizen/schedule.yml`
+- [ ] T03 — Implement `kaizen-agentic schedule validate [--target PATH]` (schema + agent name checks)
+
+### Definition of done
+
+- ADR-005 accepted; referenced from `docs/agency-framework.md`
+- Invalid schedule files fail validation with actionable errors
+- Only agents installed in the project (or fleet defaults) may appear in schedule
+
+---
+
+## Part 2 — Fleet Roster (preselected repos)
+
+Define which registered repos participate in fleet scheduling.
+
+### Roster sources (combined)
+
+| Source | Purpose |
+|--------|---------|
+| State Hub `GET /repos/` | Canonical slug list + `host_paths` |
+| Repo opt-in | `.kaizen/schedule.yml` exists and `version` set |
+| Optional hub flag | `kaizen_schedule_enabled: true` in repo metadata (design in T05) |
+
+### Tasks
+
+- [ ] T04 — Extend `docs/INTEGRATION_PATTERNS.md` Pattern 2 with roster + schedule model
+- [ ] T05 — Design doc: state-hub fields/filters for kaizen-scheduled repos (no state-hub code in this repo)
+- [ ] T06 — Spec `discover_kaizen_scheduled_repos` resolver for activity-core (inputs, output shape, errors)
+
+### Definition of done
+
+- Operators can list which repos are schedule-eligible without reading activity-core code
+- Resolver spec is sufficient for activity-core implementers to add adapter (separate repo PR)
+
+---
+
+## Part 3 — activity-core ActivityDefinitions (handoff)
+
+Generalize WP-0004 metrics definitions into **agent-run** definitions.
+
+### New reference definitions (kaizen-agentic commits drafts)
+
+| Definition | Trigger | Agent | Prepare command |
+|------------|---------|-------|-----------------|
+| `weekly-coach-orientation` | Cron Mon 09:00 | `coach` | `schedule prepare coach` |
+| `weekly-optimization-review` | Cron Mon 10:00 | `optimization` | `schedule prepare optimization` |
+| `weekly-metrics-optimize` | *(existing)* | — | `metrics optimize` |
+
+### Tasks
+
+- [ ] T07 — Add `docs/integrations/activity-definitions/weekly-coach-orientation.md`
+- [ ] T08 — Open activity-core coordination issue/PR checklist (resolver + sync + `enabled: false` pilot)
+- [ ] T17 — Document `kaizen.schedule.prepared` event payload (for future event-driven runs)
+
+### Definition of done
+
+- Definition files use `for_each` over resolver output `context.scheduled_runs`
+- Handoff checklist mirrors WP-0004 Pattern 2 activation steps
+- No scheduling code added to kaizen-agentic
+
+---
+
+## Part 4 — Dispatch Prepare CLI
+
+Bridge schedule intent to session-executable orientation.
+
+### Commands
+
+```
+kaizen-agentic schedule validate [--target PATH]
+kaizen-agentic schedule init [--target PATH]     # scaffold .kaizen/schedule.yml
+kaizen-agentic schedule prepare <agent> [--target PATH] [--format markdown|json]
+kaizen-agentic schedule list [--target PATH]       # show enabled entries from schedule.yml
+```
+
+`schedule prepare` outputs a single bundle:
+
+- Agent markdown (from installed or packaged `agents/agent-<name>.md`)
+- `memory brief <agent>` output (if memory enabled)
+- `metrics show <agent>` summary (if metrics exist)
+- Repo SCOPE/TODO pointers when present
+- Suggested session-close commands (`metrics record`, memory update)
+
+### Tasks
+
+- [ ] T09 — Implement `schedule` CLI command group skeleton
+- [ ] T10 — Wire `prepare` to memory + metrics + agent loader (reuse existing CLI internals)
+- [ ] T11 — Implement `schedule init` with sensible defaults (coach + optimization weekly, disabled tdd-workflow)
+- [ ] T12 — Tests for validate, init, prepare (temp repo fixtures)
+
+### Definition of done
+
+- `schedule prepare coach` prints non-empty orientation for a repo with agents installed
+- Prepare works offline (no State Hub required) given local `.kaizen/` state
+- CLI cheat sheet updated
+
+---
+
+## Part 5 — Pilot and Enablement
+
+Prove the loop on a small custodian repo set before fleet-wide enable.
+
+### Pilot roster (initial)
+
+- `kaizen-agentic` (dogfood)
+- `the-custodian` (hub operator)
+- One additional custodian-domain repo with `.kaizen/` state (TBD at pilot time)
+
+### Tasks
+
+- [ ] T13 — Commit pilot `weekly-coach-orientation` definition; map to custodian pilot repos
+- [ ] T14 — Commit pilot `weekly-optimization-review` definition
+- [ ] T15 — Smoke test: dry-run activity-core → manual `schedule prepare` on two repos → verify task payload
+- [ ] T16 — Operator docs: credentials, PATH, Gitea index, enabling `enabled: true` in activity-core
+- [ ] T18 — `wiki/EcosystemIntegration.md`, `CHANGELOG [Unreleased]`, `TODO.md` pointer
+
+### Definition of done
+
+- Two repos run through prepare successfully on a fixed schedule (manual or dry-run cron)
+- activity-core owners have a clear PR path to enable one definition in staging
+- Progress event recorded in State Hub at pilot completion
+
+---
+
+## Sequencing
+
+```
+Part 1 (T01–T03)  ──→  Part 4 (T09–T12)  ──→  Part 5 (T13–T16)
+        │                      │
+Part 2 (T04–T06)  ──→  Part 3 (T07–T08, T17)
+```
+
+Parts 1–2 can start in parallel. Part 4 depends on ADR + schema. Part 5 depends
+on Part 3 drafts and Part 4 `prepare`. activity-core resolver implementation
+runs in **activity-core** (parallel track after T06 spec).
+
+Estimated effort: 4–6 sessions (kaizen-agentic) + 1–2 sessions (activity-core handoff).
+
+---
+
+## Out of Scope
+
+- Implementing Temporal workflows or context resolvers in activity-core (handoff only)
+- Headless Claude Code / cloud agent runner integration (future; prepare output is runner-agnostic)
+- Scheduling all 20 agents fleet-wide in v1.3.0 (pilot: coach + optimization)
+- Replacing human review for high-risk agents (sys-medic, releaseManager)
+- WP-0007 items: agent selection wizard, template schema enforcement, doc generation
+
+---
+
+## Success Criteria
+
+1. Operators declare a **preselected repo roster** and per-repo **schedules** without tribal knowledge.
+2. activity-core can fire recurring tasks that reference `kaizen-agentic schedule prepare <agent>`.
+3. A coding-agent session opened from a scheduled task has full orientation (memory + metrics + prompt).
+4. Pilot runs on ≥2 custodian repos demonstrate the cron → task → prepare path.
+
+---
+
+## State Hub Task IDs
+
+| Code | UUID |
+|------|------|
+| T01 | f513cf74-6e32-4dce-a3bc-2995f98a30de |
+| T02 | dcb8d674-5472-4657-85bc-02ca9890fb92 |
+| T03 | 1f9a4959-d200-4d7b-8666-96472e23d820 |
+| T04 | 13ab4b76-ded2-4613-b8e2-15ab206d8c57 |
+| T05 | 685b35f3-af20-483a-9136-150f5fff68dd |
+| T06 | 5f0a0859-3ff5-4ec8-b916-35486f045b2b |
+| T07 | 2fd0f00c-5cf1-47bd-9c12-aee65bca5932 |
+| T08 | cc0565bc-ccd4-4739-9c7e-088adaa9834b |
+| T09 | 23aeff77-3429-438b-a395-5c7b5dc2824e |
+| T10 | cba9685b-408f-4292-8169-9965e7ad5c5b |
+| T11 | 7c1b049b-5566-4b5e-9d82-d9c29fab0c84 |
+| T12 | 80a8e98a-9146-4a58-8fd3-8c37f7893960 |
+| T13 | 9aee6348-d5ad-4413-b01c-5588b07c8ede |
+| T14 | 697e612b-7531-4329-82fb-b0423ba86904 |
+| T15 | 92db5130-2212-4780-ab8f-1de3adf6c6f8 |
+| T16 | bbecdcbf-42b8-4b48-9f85-e4c10e4ff3ab |
+| T17 | a9e91d4b-990a-457a-9591-d1243db5b386 |
+| T18 | 73986472-bf19-4b13-af1b-6505ab944459 |
+
+**Hub workstream:** `kaizen-wp-0006-scheduled-agent-execution` (`d4edb92b-526f-4ee4-8efe-a9fa84ab6dff`)
+
+---
+
+## Notes
+
+- WP-0004 `weekly-metrics-optimize` remains complementary; optimization agent schedule
+  may chain `schedule prepare optimization` then `metrics optimize` in task description
+- `schedule prepare` output should be stable enough for activity-core task `description` templates
+- Repo boundary: state-hub schema changes tracked in the-custodian; kaizen-agentic owns ADR + CLI + definition drafts
+- Previous WP-0005 deferrals (wizard, validate schema, doc gen) → **KAIZEN-WP-0007**
Author	SHA1	Message	Date
tegwick	2400ff4890	docs: bind WP-0006 State Hub task IDs after fix-consistency Some checks failed ci / test (push) Failing after 13m57s Details Inject hub task UUIDs from consistency sync; normalize workplan frontmatter.	2026-06-17 01:13:54 +02:00
tegwick	df899abd98	docs: add WP-0006 scheduled agent execution workplan Some checks failed ci / test (push) Has been cancelled Details Define activity-core scheduling for kaizen agents on preselected repos: schedule manifest, prepare CLI, roster resolver handoff, and custodian pilot. Point TODO/SCOPE at v1.3.0 active work.	2026-06-17 01:13:10 +02:00
tegwick	b1fceeebc8	docs: close WP-0004 workplan and bind State Hub tasks Some checks failed ci / test (push) Failing after 37s Details Add frontmatter tasks list with state_hub_task_id links and completion section for ecosystem integration (Helix, activity-core, artifact-store).	2026-06-17 01:07:12 +02:00
tegwick	fe795ca750	docs: close WP-0003 workplan and bind State Hub tasks Some checks failed ci / test (push) Failing after 38s Details Add frontmatter tasks list with state_hub_task_id links and completion section for the measurement loop (ADR-004, metrics CLI, Coach bridge).	2026-06-17 01:04:39 +02:00
tegwick	1d0999eabb	docs: close WP-0005 workplan and bind State Hub tasks Some checks failed ci / test (push) Failing after 36s Details Add frontmatter tasks list with state_hub_task_id links, completion section for v1.2.0 ship, and custodian brief from hub sync.	2026-06-17 01:02:08 +02:00