Assess scope intent and role automation readiness

.custodian-brief.md

@@ -2,7 +2,7 @@
 # Custodian Brief — kaizen-agentic
 
 **Domain:** infotech
-**Last synced:** 2026-08-20 07:49 UTC
+**Last synced:** 2026-08-20 10:06 UTC
 **State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
 
 ## Active Workstreams

INTENT.md

@@ -80,6 +80,3 @@ At maturity, it should provide enough structure for a team to define, deploy, me
 `INTENT.md` describes the stable purpose and strategic role of the repository.
 
 Changes to this file should represent a deliberate shift in what KaizenAgentic is meant to become, not ordinary scope evolution. Concrete implementation plans, product details, agent specifications, and experiments should live in PRDs, gameplans, templates, guidance documents, or implementation repositories.
-
-
-xxx

SCOPE.md

@@ -1,124 +1,190 @@
 # SCOPE
 
-> This file helps you quickly understand what this repository is about,
-> when it is relevant, and when it is not.
-> It is intentionally lightweight and may be incomplete.
-> For strategic purpose and boundaries, see `INTENT.md`.
+> This file is the operational map of the repository. For stable purpose and
+> strategic boundaries, see `INTENT.md`.
 
 ---
 
 ## One-liner
 
-KaizenAgentic: a digital talent agency framework — agent personas, project memory, measurable improvement loops, and CLI tooling for deploying continuously refining AI coding agents into Claude Code sessions.
+KaizenAgentic is the blueprint and improvement-contract layer for versioned AI
+digital talents: agent definitions, project memory, protocols, measurement and
+optimization loops, Role/engagement reference packages, and preparation tools
+for human-led or governed automated execution.
 
 ---
 
 ## Core Idea
 
-This repo is the canonical home for the **KaizenAgentic** operating model (`INTENT.md`, `wiki/`). It packages recurring development workflows as named agent personas invoked in Claude Code. The **agency layer** adds project-scoped memory (`.kaizen/agents/<name>/memory.md`) and a **Coach** meta-agent for cross-agent orientation. The **kaizen loop** — measure, analyse, refine — is defined in `wiki/` and partially implemented: `OptimizationLoop` exists in Python, but per-execution metrics collection and optimizer integration are in progress (WP-0003). Runtime execution remains Claude Code's responsibility.
+This repository turns repeatable digital work into inspectable, versioned
+artifacts. An agent blueprint defines how a task is approached; project memory
+and protocols supply local continuity; metrics and feedback provide evidence;
+and optimization proposes the next safe refinement.
+
+KaizenAgentic **declares and prepares** agent work. It does not own the clock,
+credentials, policy enforcement, or LLM session runtime. In the current
+ecosystem, activity-core decides when/what/where and emits claimable work;
+rein-aharness binds a repo-owned instance to a Kaizen blueprint and executes a
+bounded session. This separation is the implementation of the strategic
+boundary in `INTENT.md`, not an unfinished runtime hidden in this repository.
 
 ---
 
 ## In Scope
 
-- **Strategic framing**: `INTENT.md` (purpose, boundaries, design principles) and `wiki/` (mission, agent template, guidance model, brand/pricing)
-- **20 agent definitions** (`agents/agent-*.md`) — markdown persona instruction sets with YAML frontmatter (reference fleet; see `INTENT.md` boundaries)
-- **Agent categories**: project-management, development-process, code-quality, infrastructure, testing, documentation, meta
-- **Agency framework**: project memory convention (ADR-002), session-start/close protocols, Coach meta-agent (`agent-coach.md`)
-- **Protocol runbooks** (`agents/protocols/<agent>/<slug>.md`) — procedural checklists distinct from agent prompts
-- **CLI tooling** (`kaizen-agentic`): `init`, `install`, `update`, `remove`, `list`, `status`, `validate`, `templates`, `detect`, `migrate`, `extensions`, `memory` (show/init/brief/clear), `protocols` (list/show); `metrics` commands planned in WP-0003
-- **Project templates** (python-basic, python-web, python-cli, python-data, comprehensive) — agent bundles in registry code
-- **Python framework** (`src/kaizen_agentic/`): `Agent`/`AgentConfig`, `AgentRegistry`, `AgentInstaller`, `OptimizationLoop`/`PerformanceMetrics`, detection/migration/extensions
-- **Packaged agent data** (`src/kaizen_agentic/data/agents/`) — agents bundled for pip installs (sync with `agents/` via `make agents-sync-package`)
-- **Forgejo PyPI publication** — `make publish-forgejo`, tag-triggered `.forgejo/workflows/publish-python-package.yml` (v1.1.0+)
-- **Custodian MCP integration** (owned by `the-custodian`): `list_kaizen_agents()` and `get_kaizen_agent()`
-- **ADRs and workplans** for memory, protocols, workplan, and metrics conventions
+- **Operating model and product framing**: mission, agent template,
+  meta-optimizer, guidance model, business model, pricing, and brand language
+- **Reference blueprint catalog**: 20 packaged agent definitions across project
+  management, development process, code quality, testing, infrastructure,
+  documentation, and meta-improvement
+- **Blueprint authoring and distribution**: registry, validation, generated
+  documentation, packaged-data parity, installation, migration, templates, and
+  Forgejo PyPI publication
+- **Project continuity**: `.kaizen/agents/<name>/memory.md`, Coach orientation,
+  session-start/session-close conventions, and protocol runbooks
+- **Measurement and optimization**: per-agent execution records, summaries,
+  feedback, correlation, artifact publication, event emission, and optimizer
+  recommendations
+- **Scheduling contract and preparation**: `.kaizen/schedule.yml`, validation,
+  listing, scaffolding, cadence promotion, activity-definition sync, and
+  `schedule prepare` orientation bundles
+- **Agency and engagement conventions**: loop engagements, supplier-owned Role
+  packages, staffed-role lifecycle, bound agent definitions, ramp-up/down,
+  client-custodied memory, engagement metrics, and reference pilot artifacts
+- **Interoperability contracts and reference patterns** for activity-core,
+  rein-aharness, role-engine, llm-connect, State Hub, artifact-store, Helix
+  Forge, and Custodian discovery
+- **ADRs, workplans, tutorials, and integration handoffs** that make these
+  conventions human-readable and machine-consumable
 
 ---
 
 ## Out of Scope
 
-- Agent runtime / execution engine (agents are persona definitions; Claude Code executes them)
-- LLM orchestration, scheduling, or multi-agent debate systems
-- Project-specific implementation (agents guide work; they do not build the target software)
-- Custodian State Hub, MCP server code, or cross-domain governance (consumed, not owned)
-- Full KaizenGuidance codemod pipeline (vision in `wiki/KaizenGuidance.md`; not yet implemented)
-- Public pypi.org distribution (optional; the Forgejo registry is primary)
+- Running LLM sessions or operating a multi-tenant agent runtime
+- Owning cron/event schedules, durable work queues, task lifecycle, or workflow
+  execution
+- Holding credentials or granting authentication, authorization, decision
+  rights, or tool permissions
+- Live assignment of a person or agent to an organizational role
+- Owning the complete organizational role catalog; role-engine is the current
+  definition source, while this repository may consume roles and package
+  execution-oriented reference Roles
+- Customer-specific operational state as a default; client configurations,
+  vaults, targets, and private memory belong with the client/consumer
+- Every concrete agent implementation or vendor integration; this repository
+  carries a reference fleet and portable integration patterns
+- Generic AI automation unrelated to measurable continuous improvement
+- A complete KaizenGuidance codemod platform; the guidance model remains a
+  maturity target
+- Public pypi.org distribution; the Forgejo package registry is primary
 
 ---
 
 ## Relevant When
 
-- Understanding **why** KaizenAgentic exists and what it must not become (`INTENT.md`)
-- Exploring the conceptual model: agent template, optimizer, guidance, composable capabilities (`wiki/`)
-- Starting a guided development workflow (TDD, refactoring, testing, requirements, scope analysis)
-- Deploying agents with persistent cross-session memory or Coach-mediated orientation
-- Scaffolding projects with agent bundles; looking up personas via CLI or Custodian MCP
-- Contributing agent personas, protocol runbooks, or improvement-loop conventions
+- Defining, reviewing, packaging, or installing an agent blueprint
+- Adding project memory, Coach orientation, or reusable protocol runbooks
+- Measuring an agent run and turning evidence into a versioned improvement
+- Declaring a repo-local agent instance and preparing it for scheduled execution
+- Designing a staffed digital Role engagement or mapping an organizational role
+  to an executable agent blueprint
+- Integrating Kaizen work with activity-core, rein-aharness, State Hub, Helix
+  Forge, or artifact-store
+- Understanding the KaizenAgentic product and agency operating model
 
 ---
 
 ## Not Relevant When
 
-- Ad-hoc scripting with no need for structured agent guidance
-- Non-Claude-Code development environments (primary target; patterns may transfer)
-- Need for runtime orchestration, task scheduling, or autonomous agent execution
-- Repository capability profiling or SCOPE.md generation at scale (see `repo-scoping`)
+- A task needs only ad-hoc automation with no reusable agent or improvement loop
+- The need is purely schedule/runtime operation; use activity-core and the
+  selected rein/harness
+- The need is organizational role definition only; use role-engine
+- The need is identity, credentials, or authorization; use the owning identity,
+  OpenBao/credential-routing, and policy systems
+- The need is repository capability profiling or SCOPE generation at scale; use
+  repo-scoping
 
 ---
 
 ## Current State
 
-- Status: stabilizing (v1.4.0 published on Forgejo PyPI; WP-0001–0009 completed)
-- Strategic layer: `INTENT.md` and `wiki/` established; ecosystem integration docs in `wiki/EcosystemIntegration.md`
-- Implementation: 20 agents, full CLI (`metrics`, `memory`, `feedback`), agency memory + ADR-004 metrics + optimizer wiring
-- Stability: CLI stable (Click workaround in place); Forgejo CI on main; publish workflow on `v*` tags
-- Usage: internal dev projects and Custodian MCP hub-wide; pip install via Forgejo extra index
-- Active work: none; **KAIZEN-WP-0010** completed the CoulombCore distribution cleanup
+- **Release:** `1.4.0`, distributed through the Forgejo PyPI registry
+- **Blueprints:** 20 source and packaged definitions with parity validation
+- **CLI:** installation, registry, validation, memory, protocols, metrics,
+  feedback, agent authoring/docs, schedule, and engagement workflows
+- **Improvement loop:** metrics storage, summary, optimization, correlation,
+  publishing, and `kaizen.metrics.recorded` event emission are implemented
+- **Automation contract:** schedule manifests and offline prepare bundles are
+  implemented; activity-core has a durable `ops_run` queue and rein-aharness has
+  a live claim loop plus a generic `agent-session` approach
+- **Agency model:** one supplier Role package and one staffed host-operator pilot
+  prove the file conventions; broader role-catalog integration is not yet
+  standardized
+- **Repository health:** Forgejo CI, release checks, agent validation, and
+  metadata/workplan conventions are normalized through KAIZEN-WP-0011
+- **Open maturity gap:** a canonical role-definition → assignment → agent-instance
+  contract and an end-to-end role-based pilot remain to be implemented
 
 ---
 
 ## How It Fits
 
-- Upstream dependencies: Claude Code (agent invocation), kaizen continuous-improvement philosophy
-- Downstream consumers: Custodian State Hub (MCP agent discovery); domain repos that install agents and maintain `.kaizen/` state
-- Often used with: `the-custodian` (MCP integration), `markitect_project` (project-management patterns), `activity-core` (scaffolding references), `repo-scoping` (SCOPE.md generation)
+| Concern | Owning system | KaizenAgentic relationship |
+|---|---|---|
+| Organizational role definitions | `role-engine` | Consume stable role references and translate duties/evidence into blueprint inputs |
+| Agent blueprints and improvement | `kaizen-agentic` | Own |
+| Repo-local agent instance | Consuming repository | Define through `.kaizen/` contracts owned jointly with runtime extensions |
+| Scheduling and claimable work | `activity-core` | Supply manifests, definitions, prepare commands, and event contracts |
+| Governed unattended execution | `rein-aharness` (selected rein) | Supply blueprint/orientation bundle; receive metrics and improvement evidence |
+| Model/provider abstraction | `llm-connect` | Runtime dependency outside this repository |
+| Credentials and authorization | OpenBao/credential routing, identity and policy systems | Reference named routes/profiles only; never hold grants or secrets |
+| Durable coordination evidence | Custodian State Hub | Publish/index progress and workplan state; do not own hub code |
+
+The workspace currently has `role-engine`, not a component named
+`role-manager`. Role-engine explicitly excludes live assignment and execution.
+An assignment/binding contract therefore needs an explicit owner before roles
+can be automated at scale.
 
 ---
 
 ## Terminology
 
-- Preferred terms: KaizenAgentic (product), agent, agent persona, agency, project memory, protocol runbook, Coach, kaizen loop
-- Also known as: "kaizen agents", "kaizen-agentic" (repo/package slug), "the agent library"
-- Potentially confusing terms: "Agent" is a persona/instruction set, not a running process; "agency" means memory + coaching, not autonomous orchestration; repo slug `kaizen-agentic` vs product name `KaizenAgentic`
-
----
-
-## Related / Overlapping Repositories
-
-- `the-custodian` — hosts MCP tools that load agents; integration code lives there, not here
-- `repo-scoping` — generates/refreshes SCOPE.md from approved characteristics
-- `markitect_project` — references kaizen-agentic as a capability submodule
-- `sys-medic` (source repo) — origin of sys-medic agent; canonical copy in `agents/agent-sys-medic.md`
+- **Blueprint / agent definition**: versioned instructions for how an agent
+  performs a kind of work; not a running process
+- **Role definition**: organizational contract for outcomes, responsibilities,
+  authority, interfaces, escalation, and evidence; not an identity or grant
+- **Role package**: KaizenAgentic's execution-oriented reference product
+  containing blueprint/protocol/ramp assets; currently not the canonical
+  organization-wide role catalog
+- **Assignment / binding**: a record that selects who or what fills a role in a
+  specific context; ownership is not yet standardized
+- **Instance**: consumer-owned declaration binding a blueprint to target,
+  cadence, policy lane, tool profile, budget, memory, and metrics
+- **Engagement**: a client-scoped lifecycle and custody boundary for staffed work
+- **Harness / rein**: governed runtime that executes an instance; not owned here
+- **Agency**: the memory, coaching, measurement, and engagement operating model;
+  not unconstrained autonomous orchestration
 
 ---
 
 ## Getting Oriented
 
-Read in this order for full context:
+Read in this order:
 
-1. `INTENT.md` — stable purpose, boundaries, design principles
-2. `wiki/KaizenAgenticMission.md` — product narrative and key components
-3. `wiki/EcosystemIntegration.md` — how KaizenAgentic composes with adjacent repos
-4. `wiki/KaizenAgentTemplate.md` — intended agent specification format
-5. `README.md` — quick start and agency overview
-6. `docs/agency-framework.md` — memory, coach, protocols, metrics (ADR-004)
-7. `history/` — persisted assessments and gap analyses
-8. `workplans/` — active implementation roadmap
+1. `INTENT.md` — stable purpose and strategic boundaries
+2. `docs/assessments/2026-08-20-intent-role-automation-readiness.md` — current
+   intent fit and role-automation path
+3. `README.md` — install and daily CLI entry points
+4. `docs/agency-framework.md` — memory, Coach, protocols, metrics, and schedules
+5. `docs/adr/ADR-005-scheduled-agent-execution.md` — scheduling boundary
+6. `docs/adr/ADR-007-forward-deployed-engagement-convention.md` — staffed Roles
+7. `docs/INTEGRATION_PATTERNS.md` — ecosystem handoffs
+8. `workplans/` — implementation history and active work
 
-Key directories: `wiki/` (conceptual model), `agents/` (personas), `agents/protocols/` (runbooks), `src/kaizen_agentic/` (Python framework), `docs/adr/` (conventions)
-
-Entry points: `kaizen-agentic --help`; MCP: `get_kaizen_agent("scope-analyst")`; docs: `docs/GETTING_STARTED.md`, `docs/AGENT_DISTRIBUTION.md`
+Key directories: `agents/`, `agents/protocols/`, `roles/`, `engagements/`,
+`src/kaizen_agentic/`, `docs/adr/`, and `wiki/`.
 
 ---
 
@@ -126,42 +192,54 @@ Entry points: `kaizen-agentic --help`; MCP: `get_kaizen_agent("scope-analyst")`;
 
 ```capability
 type: process
-title: Guided development agent personas
-description: Named markdown instruction sets for TDD, refactoring, documentation standards, requirements engineering, and project management workflows in Claude Code sessions.
-keywords: [agents, personas, tdd, refactoring, claude-code, workflows]
+title: Versioned agent blueprints and protocols
+description: Twenty packaged digital-talent definitions plus reusable runbooks for guided software and operational work.
+keywords: [agents, blueprints, personas, protocols, digital-talent]
 ```
 
 ```capability
 type: infrastructure
 title: Agent deployment and project scaffolding CLI
-description: Install, update, validate, and bundle agents into new or existing projects via the kaizen-agentic CLI and registry-backed templates.
+description: Install, update, validate, author, document, and bundle agents in new or existing repositories.
 keywords: [cli, install, templates, scaffolding, registry]
 ```
 
 ```capability
 type: process
-title: Project-scoped agent memory and coaching
-description: Convention and CLI for .kaizen/agents memory files, session protocols, and Coach-mediated orientation briefs across a deployed agent fleet.
-keywords: [memory, coach, agency, kaizen, cross-session]
+title: Project memory, coaching, and engagement lifecycle
+description: Conventions and tooling for project-scoped memory, Coach orientation, staffed Role engagements, ramp-up/down, and client-custodied evidence.
+keywords: [memory, coach, agency, engagement, roles]
 ```
 
 ```capability
-type: infrastructure
-title: Kaizen agent discovery via Custodian MCP
-description: Single source of truth for agent definitions consumed by the Custodian State Hub list_kaizen_agents and get_kaizen_agent tools.
-keywords: [mcp, custodian, discovery, agent-library]
+type: data
+title: Agent measurement and optimization evidence
+description: Record, summarize, correlate, publish, and emit agent performance evidence for versioned improvement decisions.
+keywords: [metrics, feedback, optimization, evidence, events]
+```
+
+```capability
+type: integration
+title: Scheduled-agent declaration and preparation
+description: Validate repo-local schedules and assemble offline orientation bundles for activity-core-triggered, harness-executed runs.
+keywords: [schedule, activity-core, rein-aharness, preparation, automation]
 ```
 
 ```capability
 type: process
-title: KaizenAgentic conceptual model and agent specification standards
-description: Strategic framing, design principles, agent template, optimizer spec, and improvement philosophy via INTENT.md and wiki/.
-keywords: [kaizen, intent, template, optimization, digital-talent-agency]
+title: KaizenAgentic operating model and specification standards
+description: Strategic framing, design principles, agent template, optimizer model, and product/agency conventions for continuously improving digital talents.
+keywords: [kaizen, intent, template, optimization, operating-model]
 ```
 
 ---
 
 ## Notes
 
-- `agents/` (20 files) is the development source of truth; `src/kaizen_agentic/data/agents/` must stay in sync (enforced in WP-0005 T09–T10)
-- Agent definitions use minimal frontmatter today; full `wiki/KaizenAgentTemplate.md` conformance is a maturity target, not current reality
+- `agents/` is the development source for the 20 reference definitions;
+  `src/kaizen_agentic/data/agents/` must remain synchronized with
+  `make agents-sync-package`.
+- Agent definitions still use less structure than the full
+  `wiki/KaizenAgentTemplate.md`; schema conformance is a maturity gap.
+- `.kaizen/schedule.yml` base fields are owned here. rein-aharness adds runtime
+  policy extensions and validates them separately.

WORK-RECORDS.md

@@ -19,6 +19,7 @@
 | workplan | KAIZEN-WP-0009 | finished | — | workplans/KAIZEN-WP-0009-forward-deployed-agency.md |
 | workplan | KAIZEN-WP-0010 | finished | — | workplans/KAIZEN-WP-0010-forgejo-pypi-migration.md |
 | workplan | KAIZEN-WP-0011 | finished | — | workplans/KAIZEN-WP-0011-repository-health-normalization.md |
+| workplan | KAIZEN-WP-0012 | finished | — | workplans/KAIZEN-WP-0012-scope-intent-role-automation-assessment.md |
 | task | T01 | done | — | workplans/KAIZEN-WP-0003-measurement-loop.md |
 | task | T02 | done | — | workplans/KAIZEN-WP-0003-measurement-loop.md |
 | task | T03 | done | — | workplans/KAIZEN-WP-0003-measurement-loop.md |
@@ -133,3 +134,7 @@
 | task | KAIZEN-WP-0011-T03 | done | — | workplans/KAIZEN-WP-0011-repository-health-normalization.md |
 | task | KAIZEN-WP-0011-T04 | done | — | workplans/KAIZEN-WP-0011-repository-health-normalization.md |
 | task | KAIZEN-WP-0011-T05 | done | — | workplans/KAIZEN-WP-0011-repository-health-normalization.md |
+| task | KAIZEN-WP-0012-T01 | done | — | workplans/KAIZEN-WP-0012-scope-intent-role-automation-assessment.md |
+| task | KAIZEN-WP-0012-T02 | done | — | workplans/KAIZEN-WP-0012-scope-intent-role-automation-assessment.md |
+| task | KAIZEN-WP-0012-T03 | done | — | workplans/KAIZEN-WP-0012-scope-intent-role-automation-assessment.md |
+| task | KAIZEN-WP-0012-T04 | done | — | workplans/KAIZEN-WP-0012-scope-intent-role-automation-assessment.md |

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.

workplans/KAIZEN-WP-0012-scope-intent-role-automation-assessment.md

@@ -0,0 +1,77 @@
+---
+id: KAIZEN-WP-0012
+type: workplan
+title: "Scope, intent, and role automation readiness assessment"
+domain: agents
+repo: kaizen-agentic
+status: finished
+owner: codex
+topic_slug: custodian
+created: "2026-08-20"
+updated: "2026-08-20"
+---
+
+# KAIZEN-WP-0012 — Scope, intent, and role automation readiness assessment
+
+## Reconcile SCOPE with implemented capabilities
+
+```task
+id: KAIZEN-WP-0012-T01
+status: done
+priority: high
+```
+
+Refresh `SCOPE.md` from the current repository state, including metrics,
+engagement, Role package, scheduling-contract, and ecosystem boundaries.
+
+**Result:** `SCOPE.md` now describes the implemented blueprint, measurement,
+schedule, engagement, and integration surfaces and assigns runtime, schedule,
+role-catalog, assignment, credential, and policy ownership explicitly.
+
+## Assess repository against INTENT
+
+```task
+id: KAIZEN-WP-0012-T02
+status: done
+priority: high
+```
+
+Map the implemented system and known gaps to the stable purpose, ownership
+boundaries, design principles, and maturity target in `INTENT.md`.
+
+**Result:** the dated assessment records strong intent alignment, incomplete
+template/idempotency/refinement maturity, and the remaining path to the full
+define/deploy/measure/refine/commercialize target. Stray trailing draft text was
+removed from `INTENT.md` without changing its strategy.
+
+## Define automated role-agent readiness path
+
+```task
+id: KAIZEN-WP-0012-T03
+status: done
+priority: high
+```
+
+Document the existing activity-core → rein-aharness execution path and the
+remaining contracts, ownership decisions, controls, and pilot work needed to
+schedule agents that perform role-engine-defined roles.
+
+**Result:** the readiness document traces the existing live scheduling/runtime
+backbone, identifies the absent assignment owner and structured run fields,
+assigns changes by repository, and proposes a read-only Community Manager pilot.
+
+## Validate and close out
+
+```task
+id: KAIZEN-WP-0012-T04
+status: done
+priority: medium
+```
+
+Run documentation, repository, test, and State Hub consistency checks; record
+the evidence and leave workplan status synchronized with the result.
+
+**Result:** full pytest, `make release-check`, `make agents-validate`, and
+`git diff --check` pass. `statehub fix-consistency` passes with the existing
+capability-tag advisory and production-registrar deferral for workplan UUIDs;
+the generated work-record index includes KAIZEN-WP-0012.