tegwick cfc1b75157 Harness foundation: INTENT, ADR-001, architecture, prototype adoption

- INTENT.md: three-layer model (blueprint/instance/harness), single
  shared runtime, never-become boundaries
- ADR-001 (accepted): DEC-2026-002 resolution — one harness repo for
  all projects; instances are declarative state in consuming repos
- docs/architecture.md: components, contracts (manifest, tool
  profiles, completion events, credential lanes), deployment shape
- agent_harness/: executor-worker prototype adopted and renamed
  (6/6 tests green); HARNESS-WP-0001 initial workplan (7 tasks)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-17 23:35:27 +02:00

3.4 KiB

Raw Blame History

INTENT

This file explains why agent-harness exists — the problem it solves, the principle that governs its boundaries, and what it must never become. Established by DEC-2026-002 (binky-control DecisionQueue, resolved 2026-07-17) and ADR-001 in this repo.

Why it exists

Agentic work in the ecosystem requires combining many rapidly evolving ingredients: agent blueprints (kaizen-agentic), LLM compute (llm-connect), scheduling (activity-core), credentials (OpenBao/ops-warden), policy gates (net-kingdom/flex-auth), memory (phase-memory, .kaizen/ state), and reporting (Custodian State Hub). Without a shared runtime, every project that wants unattended agents must re-wire all of this — and every base- technology shift multiplies into N project upgrades. The first concrete casualty: binky-control's daily rhythm depended on a workstation cron bridge because no workstation-independent runtime existed.

agent-harness exists so that any project can run governed, unattended agent instances by committing a small declarative manifest — while all the fast-evolving wiring lives, evolves, and is enforced in exactly one place.

The governing principle: three layers

Blueprint (class) — owned by kaizen-agentic. Versioned, reusable, centrally improved agent definitions.
Instance — owned by the consuming repo. Declarative state only: which blueprints run, cadence, autonomy lane, named tool profile, budget, plus .kaizen/ memory and metrics. Never code, never credentials, never tool wiring.
Harness (runtime) — this repo. The single shared, multi-tenant runtime: consumes tasks emitted by activity-core, loads the blueprint (ADR-005 schedule prepare), binds instance state, acquires credentials, runs the bounded agentic session via llm-connect, verifies the local commit, reports to the State Hub and to the instance's kaizen metrics.

The harness is the only credential holder and the only policy enforcement point for agent sessions. Instances declare policy; the harness enforces it. Instances pin a harness major version; upgrades happen centrally.

Strategic role

This is the "federated execution" half of the hub-and-spoke AgentOps model (agentic-resources intent): central standards and runtime, per-repo instances. It closes the gap the other repos deliberately leave open — activity-core answers when/what/where and does not execute; kaizen-agentic declares and prepares and does not invoke LLMs; llm-connect abstracts providers and does not orchestrate.

What it must never become

Not a scheduler. Triggering and task emission stay in activity-core. The harness only consumes.
Not a blueprint author. Agent definitions, measurement conventions, and improvement loops stay in kaizen-agentic.
Not a per-project logic container. Anything specific to one tenant belongs in that tenant's manifest or blueprint — the harness stays generic or the instance model has failed.
Not an LLM abstraction. Provider handling stays in llm-connect.
Not a state store. Run history, task lifecycle, and decisions live in the State Hub; agent memory lives with the instance (and later phase-memory profiles).
Not autonomous beyond its grant. Sessions run under named tool profiles with hard allow-lists; the harness never pushes beyond the target repo grant and never widens its own permissions.