kaizen-agentic/docs/assessments/2026-08-20-intent-role-automation-readiness.md

INTENT Alignment and Role-Agent Automation Readiness

Date: 2026-08-20

Workplan: KAIZEN-WP-0012

Assessment: materially aligned, operationally useful, not yet at the full INTENT.md maturity target

Executive assessment

KaizenAgentic has grown beyond the prompt library described by the previous SCOPE.md. It now provides most of the blueprint and improvement-contract layer required by INTENT.md: versioned agent definitions, project memory, protocols, execution metrics, feedback, optimizer recommendations, schedule manifests, preparation bundles, engagement conventions, and a pilot Role package.

The strategic boundary remains sound. KaizenAgentic should not absorb runtime, scheduling, credentials, authorization, or durable task lifecycle. Those pieces now exist elsewhere:

• role-engine defines organizational roles;
• activity-core schedules activity and emits durable claimable ops_run work;
• rein-aharness claims work and runs governed agent sessions;
• llm-connect supplies provider-neutral model execution;
• identity, OpenBao/credential routing, and policy systems control access;
• State Hub and repo-local .kaizen/ state retain coordination and improvement evidence.

The missing link is a governed, machine-readable chain from a role definition to a specific agent assignment and executable instance. The runtime path itself is no longer hypothetical: activity-core's queue and rein-aharness's generic agent-session approach are implemented. However, the current queue payload and harness intake do not carry an explicit role, assignment, or arbitrary agent-instance reference. Rein-aharness currently infers the agent from a small fixed definition/label map and otherwise defaults to coach.

Naming and ownership finding

No repository, service, or contract named role-manager was found in the workspace on 2026-08-20. The current role-definition repository is role-engine; its INTENT.md is still marked Draft.

This matters because role-engine's INTENT.md explicitly says:

• roles are not identities;
• role definitions do not grant permissions;
• live assignment, scheduling, and workflow execution are out of scope;
• machinery should be added only for demonstrated consumer requirements.

Therefore “roles as defined by role-manager” is treated here as “roles defined by role-engine.” A separate assignment/binding owner is still required. It could be a deliberately introduced role-manager service, a consumer-owned assignment manifest indexed by State Hub, or an extension of an existing system—but that ownership decision should be explicit rather than silently changing role-engine's purpose.

Assessment against INTENT.md

INTENT commitment	Current evidence	Assessment
Canonical mission and operating model	INTENT.md, wiki, ADRs, agency and engagement documents	Strong
KaizenAgent definition template	Template exists; authoring/docs CLI and 20 packaged definitions exist	Partial: the reference fleet still uses less structure than the full template
Meta-optimizer concept	OptimizationLoop, metrics summaries, metrics optimize, feedback and correlation	Strong foundation; refinement approval/version rollout is not closed-loop
Measurable behavior	Execution JSONL, summaries, engagement metrics, event and artifact publication	Implemented, but coverage depends on callers recording closeout evidence
Idempotent behavior	Idempotency keys exist in engagement closeout and downstream ops_run; validation is repeatable	Partial: generic blueprint definitions do not yet declare convergence/idempotency semantics uniformly
Codebase improvement guidance	Specialized agents, protocols, templates, tutorials, integration patterns	Useful reference implementation; machine-checkable guidance model remains incomplete
Relationship among prompts, experiments, mantras, agents, capabilities	Conceptual material and capability metadata exist	Partial: relationships are documented more than schema-validated
Product, pricing, revenue, and brand framing	Agency model, Role packages, Kai pilot settlement, wiki framing	Present at pilot level; not yet a repeatable commercial operating system
Versioned, testable, reversible units	Package releases, Git history, tests, Role version, ADRs	Strong for code and packages; blueprint compatibility/pinning needs a formal contract
Define → deploy → measure → refine → commercialize	Define/deploy/measure are operational; refine and commercialize have working pieces	Maturity target not yet complete

Design-principle fit

• Continuous improvement: directly represented in metrics, feedback, memory, optimization, and engagement closeout.
• Measurable by default: supported by tooling, but not yet mandatory in every agent definition or automated run result.
• Idempotent operations: present in selected workflows, not expressed as a required blueprint field or verified per duty.
• Evidence over intuition: strong conventions and event/artifact paths exist; optimizer recommendations still require a clearer promotion gate.
• Separation of concerns: strong and increasingly proven by the activity-core / rein-aharness split.
• Composable capabilities: agents, protocols, memory, schedules, Roles, and integrations are composable, though their shared schema is fragmented.
• Human-readable and machine-executable: human-readable coverage is strong; role-engine roles are not yet machine-readable enough for safe compilation.
• Rollback-ready evolution: Git/package rollback exists; assignment, blueprint pinning, and canary policy need standardization.
• Compounding value: evidence can accumulate, but automatic evidence → approved blueprint revision → controlled rollout is not closed.

What already works end to end

The ecosystem has the following proven backbone:

activity-core Temporal schedule/event
        │
        ▼
rule action → durable ops_run (idempotent, lease/claim/retry)
        │
        ▼
rein-aharness claim-loop → approach selection
        │
        ▼  labels/approach_hint = agent-session
repo instance policy → kaizen-agentic schedule prepare
        │
        ▼
bounded LLM session → local commit verification
        │
        ▼
ops_run result + State Hub progress + .kaizen metrics

Important existing controls include:

• unique per-fire ops_run idempotency keys;
• atomic claim with lease, heartbeat API, retry, and terminal failure;
• target-repository mapping on the harness host;
• named tool profiles, autonomy lanes, token budgets, and harness-major pins;
• offline blueprint/memory/metrics preparation;
• local commit verification and no-push runtime policy;
• completion metadata and artifact links in activity-core;
• per-agent metrics and State Hub progress reporting.

This means the next work is integration and governance, not building another scheduler or agent runtime.

The missing role-to-run contract

Four distinct records must remain separate:

Record	Question answered	Recommended owner
RoleDefinition	What outcomes, duties, authority, interfaces, and evidence define the role?	role-engine
AgentBlueprint / executable Role package	How can an agent perform a safe subset of those duties?	kaizen-agentic
RoleAssignment	Which agent instance fills which role, for whom, on what targets and dates?	Explicit new owner or consumer-owned manifest indexed centrally
AgentInstance	Which blueprint, cadence, lane, profile, budget, memory, and runtime pin apply?	Consuming repository, validated by kaizen-agentic and the selected rein

The first implementation should define a versioned RoleAssignment contract with at least:

• stable assignment ID and lifecycle state;
• role_ref containing role ID plus immutable revision/version;
• blueprint_ref containing agent name plus package/version or content digest;
• client/tenant and one or more target references;
• duty selection: only the role duties delegated to this agent;
• expected outputs and evidence for each duty;
• cadence/event trigger references and timezone;
• autonomy lane, named tool profile, token/time budget, and harness-major pin;
• credential-route references, never secret values;
• approval and escalation rules derived from role decision rights;
• memory/metrics custody location and retention classification;
• start/end dates, pause/disable switch, owner, and rollback revision.

Required changes by repository

role-engine

1. Add stable revision metadata or a small machine-readable companion format after agreeing the consumer need.
2. Structure at least duties, cadence suggestions, decision rights, escalations, interfaces, and success evidence.
3. Preserve the human-readable role contract as authoritative.
4. Do not add assignment, credentials, or scheduling merely to make the catalog look executable.

kaizen-agentic

1. Define a role_ref and duty-coverage mapping for executable Role packages.
2. Reconcile the local roles/<id>/ROLE.yaml concept with role-engine: the former should be a derived execution package, not a competing organizational role source.
3. Add a compiler/scaffolder that consumes a pinned role definition plus an assignment and produces:
   • a bound agent blueprint;
   • protocols and success metrics;
   • .kaizen/schedule.yml base/runtime fields;
   • activity-core definition/rule fragments;
   • validation evidence showing which role duties are covered or excluded.
4. Add schema validation for blueprint version, role revision, idempotency, expected output, evidence, and escalation metadata.
5. Close the improvement promotion loop: evidence → proposed blueprint change → tests/evaluation → human approval → versioned canary → rollback or promote.

activity-core

1. Keep schedule and queue ownership.
2. Extend the task/ops_run contract with structured execution metadata instead of encoding it only in labels or prose. Minimum useful fields are assignment_id, role_id, duty_id, agent_instance, blueprint_ref, expected_output, and a correlation/run key.
3. Emit labels: [automated, agent-session] and approach_hint: agent-session for governed agent sessions.
4. Resolve only active, enabled assignments and generate a unique run for each (assignment, duty, target, scheduled fire).
5. Keep prompts, credentials, and raw model output out of ops_run records.

rein-aharness

1. Keep runtime, credentials, policy enforcement, and claim execution ownership.
2. Replace fixed label-to-agent inference for role sessions with an explicit validated agent_instance/blueprint reference from the run contract.
3. Verify the run's assignment is active and its role/blueprint/runtime versions match the repo manifest.
4. Enforce duty-level tool profile, target allow-list, budget, timeout, concurrency, and escalation policy.
5. Return compact structured evidence: outcome, artifact path, commit, target, blueprint/role/assignment revisions, metrics, and refusal/escalation reason.
6. Separate deterministic connectors from the LLM session. For example, Telegram collection or publishing should be bounded adapters; the model should receive prepared data and should not gain arbitrary network access.

State Hub and policy/identity systems

1. Index assignments and correlation IDs without becoming the role source or runtime.
2. Connect activity_run → ops_run → harness execution → artifact/commit → kaizen metrics for review and audit.
3. Represent human-needed/refused/escalated outcomes explicitly.
4. Route credential needs through the catalog/OpenBao path and enforce technical authorization independently of role wording.

Proposed instance shape

This is a target contract, not the current kaizen schedule schema:

version: "2"
timezone: Europe/Berlin
harness: 0
assignments:
  community-manager-coulomb:
    role_ref:
      repository: role-engine
      id: community-manager
      revision: "<immutable-git-revision>"
    blueprint_ref:
      name: community-manager
      package_version: "<kaizen-agentic-version>"
    target: coulomb-society-operations
    duties:
      weekly-community-health:
        cadence: weekly
        cron: "0 9 * * 1"
        enabled: true
        expected_output: reports/community-health/YYYY-MM-DD.md
        lane: green
        tool_profile: community-observe-report
        budget: 40000
        approval: none
      publication-draft:
        cadence: weekly
        enabled: false
        expected_output: outbox/community-update-YYYY-MM-DD.md
        lane: green
        tool_profile: community-draft-only
        approval: human-before-publish

The assignment compiler could initially render this into the current v1 .kaizen/schedule.yml plus an activity-core definition. Moving the base schedule schema to v2 should happen only after kaizen-agentic, activity-core, and rein-aharness agree the fields and compatibility path.

Recommended first pilot

Use role-engine's only current role, community-manager, but automate a narrow, low-risk duty rather than claiming the entire role is autonomous.

Pilot duty: produce a weekly community-health brief from an approved, read-only snapshot of community activity.

Why this duty: it exercises role revision, assignment, scheduled intake, blueprint preparation, evidence metrics, and escalation without granting publishing, moderation, sanctions, membership, or direct messaging authority.

Pilot sequence:

1. Pin the role-engine revision and identify which Community Manager success criteria the brief measures.
2. Create a Kaizen blueprint/protocol and tests for evidence quality, provenance, privacy handling, and “insufficient evidence” refusal.
3. Create a consumer-owned assignment and strict read/report-only instance.
4. Have a deterministic adapter place a sanitized activity snapshot in the target repo or artifact input; do not expose general Telegram credentials to the model session.
5. Register an activity-core weekly definition that emits an agent-session run with explicit assignment and duty identity.
6. Run through rein-aharness, producing only a local report commit.
7. Require human review and measure correctness, provenance, usefulness, false assertions, runtime, tokens, and escalation quality.
8. Complete five clean scheduled/forced cycles before removing any manual fallback or considering a write-capable duty.

Only after the observation/reporting pilot is stable should the system add drafting to a human-reviewed outbox. Automatic publishing or moderation should remain separate, more privileged duties with explicit policy and approval.

Operational definition of “fully automated”

For this system, fully automated should mean:

• the schedule/event fires without a person;
• an eligible assignment resolves deterministically;
• work is emitted once, claimed safely, and retried within policy;
• the exact role, duty, blueprint, target, runtime, and policy versions are known before execution;
• the agent receives bounded context and tools;
• success is verified against an explicit output/evidence contract;
• results and costs are correlated and reviewable;
• refusal, escalation, pause, rollback, and lease recovery work without manual database repair.

It should not mean that every responsibility in a human role is delegated or that role wording grants technical authority. A role can be fully scheduled while only its safe, explicitly assigned duties are automated.

Recommended implementation order

1. Ownership decision: confirm role-engine as definition source and choose the assignment/binding owner and canonical name.
2. Contracts: role revision metadata, RoleAssignment v1, role-to-blueprint coverage, and structured ops_run execution context.
3. Adapters and validation: kaizen compiler/scaffolder plus explicit role-agent intake in rein-aharness.
4. Read-only pilot: Community Manager weekly health brief, human-reviewed, five clean cycles.
5. Production controls: dashboards, alerts, retry/dead-letter policy, pause/rollback, version canary, secret-route/policy audit.
6. Improvement closure: use measured pilot evidence to version and canary a blueprint refinement without rewriting the source role contract.

This route reuses the platform that is already live, preserves each repository's stated intent, and concentrates new work on the one genuinely missing capability: governed role assignment and binding.