kaizen-agentic/docs/integrations/activity-core-handoff-engagement.md

activity-core Handoff — Customer Engagement Bootstrap (WP-0008)

Coordination requirements for activity-core to support coulomb-loop-style customer engagements after kaizen-agentic ships schedule init --engagement and metrics record --emit-event.

Open as an activity-core issue titled "Engagement bootstrap: event-payload + bootstrap cadence alignment".

Supplier capabilities (kaizen-agentic — done)

• schedule init --engagement <slug> --agents coach,optimization --bootstrap-cadence hourly
• metrics record --emit-event → activity.kaizen.metrics.recorded
• Resolver contract: discover-kaizen-scheduled-repos.md

activity-core requirements

R1 — event-payload context resolver (blocks LOOP-WP-0002 event path)

Problem: Event-triggered definitions bind context.metrics via type: event-payload, but resolve_context treats unknown types as {}.

Requirement: Register a resolver (or inline handler) that, when event_envelope_json is present, binds EventEnvelope.attributes to the bind_to key (stripping context. prefix).

context_sources:
  - type: event-payload
    bind_to: context.metrics

Expected snapshot after resolve:

{"metrics": {"agent": "coach", "project": "kaizen-agentic", "summary": {...}}}

Acceptance: Manual NATS publish of a kaizen-metrics-recorded-event envelope triggers low-success-rate-review and evaluates context.metrics.summary.success_rate without binding {}.

R2 — Bootstrap cadence enum vs cron (blocks mis-tuned filters)

Problem: Engagement bootstrap writes hourly cron expressions but keeps cadence: daily in .kaizen/schedule.yml (coulomb-loop ADR-003 convention). Customer ActivityDefinitions filter discover_kaizen_scheduled_repos with cadence: daily.

Requirement: Do not require cadence: hourly in schedule.yml (invalid in ADR-005 schema). Continue matching on the cadence enum field; rely on per-repo cron overrides for hourly firing.

Acceptance: Resolver with cadence: daily returns pilot repos whose schedule.yml contains cron: "15 * * * *" / "30 * * * *".

R3 — ActivityDefinition cron alignment

Customer coulomb definitions offset from repo schedule crons:

Definition	activity-core cron	Repo schedule cron
hourly-metrics-optimize	0 * * * *	(metrics path; no schedule)
hourly-coach-orientation	15 * * * *	coach 15 * * * *
hourly-optimization-review	30 * * * *	optimization 30 * * * *

Requirement: Keep definition crons and repo schedule crons in sync during bootstrap. Document in customer handoff that schedule init --engagement presets must match enabled ActivityDefinition offsets.

R4 — Event router registration

Requirement: Ensure kaizen.metrics.recorded is an allowed event type in event_type_registry (if registry is enforced on publish path).

Acceptance: Event router dispatches to enabled low-success-rate-review definitions when envelope type matches.

R5 — Engagement roster path (optional v1.1)

Customer rosters live in the engagement repo (e.g. coulomb-loop/loops/kaizen-stack/roster.yaml), not in target repos.

Suggestion: Support optional resolver param engagement_slug that looks up roster path from a hub field or env KAIZEN_ENGAGEMENT_ROSTER so definitions need not hard-code absolute paths.

Smoke sequence (end-to-end)

# Target repo (supplier runs on pilot)
kaizen-agentic schedule init --engagement coulomb-loop \
  --agents coach,optimization --bootstrap-cadence hourly --force
kaizen-agentic schedule validate
kaizen-agentic memory init coach && kaizen-agentic memory init optimization

# Record + emit (requires nats-py)
kaizen-agentic metrics record coach --success --time 60 --quality 0.9 --emit-event

# activity-core
# 1. Resolver dry-run: discover_kaizen_scheduled_repos + cadence=daily → 6 runs
# 2. Event dry-run: publish sample envelope → low-success-rate-review tasks

Related

• customer engagement playbook (supplier)
• coulomb-loop docs/integrations/activity-core-handoff.md (customer)
• KAIZEN-WP-0008