Assess scope intent and role automation readiness

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

@@ -0,0 +1,340 @@
+# 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:
+
+```text
+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:
+
+```yaml
+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.