rein-aharness/SCOPE.md

# SCOPE

> Capability snapshot: 2026-09-04. `INTENT.md` states the destination and
> boundaries; this file records what the repository currently implements and
> has evidence for.

## One-liner

`rein-aharness` is the Claude-Code-CLI-oriented rein that claims scheduled
Activity Core work, routes versioned execution profiles through Glas, and
retains a legacy set of local task executors for unattended repository work.

## Implemented capability

### Intake and lifecycle

- The primary production intake is the Activity Core `ops_run` REST queue.
  The worker filters and claims rows, heartbeats their lease, and completes or
  fails them with normalized result data.
- A queued `harness_profile_ref` is authoritative. The worker carries its
  allowlisted attribution refs into a Glas `ExecutionRequest`, uses governed
  actor `agt`, returns the complete `GatewayResult`, and never falls back to a
  legacy approach after profile refusal or failure.
- Profile-absent rows use the coexistence registry in `approaches.py`.
  Dispatch requires an explicit, non-expired
  `AGENT_HARNESS_LEGACY_APPROACHES_UNTIL` date; unmatched or disabled routes
  fail visibly. JSON task files remain available for local development, and
  issue-core polling remains as a legacy compatibility path.
- The production claim loop is a single-concurrency user systemd service on
  railiance01. Claim failures use the configured poll interval and active runs
  receive lease heartbeats.

### Execution paths

- Generic local `TaskSpec` runs resolve instance policy, optionally load a
  kaizen-agentic persona bundle, invoke Claude Code in the target checkout,
  impose a wall-clock timeout and named Claude tool allow-list, and require a
  new Git `HEAD` before reporting success.
- Local task files may carry an explicit v1 `repository_grant`. These runs
  validate commit ancestry/count, changed paths, clean post-state, protected Git
  metadata, and remote refs under the repository transaction before success.
- Optional Claude stream JSON is reduced to tool/hook audit events and can be
  reported to State Hub.
- Versioned profiled rows delegate profile, rein, model, tool, sandbox, and
  teardown decisions to Glas/sand-boxer. `rein-aharness` owns the queue
  adapter, not the meta-framework or sandbox implementation.
- Legacy structured executors produce Freedom Intelligence daily research
  briefs, Binky daily/weekly briefs, deterministic mailbox scans, and mailbox
  triage. The LLM-backed structured paths use the llm-connect HTTP service;
  mailbox credential acquisition is a bounded OpenBao/AppRole pre-step.
- A deterministic smoke path can clone a controlled sandbox repository,
  commit `SMOKE.md`, optionally push it, and report evidence without invoking
  Claude.

### Declarative policy and reporting

- `.kaizen/schedule.yml` parsing and validation cover cadence, enabled state,
  blueprint name, green/blue lane, named tool profile, token budget, and
  harness-major pin. Strict validation requires the runtime fields for enabled
  instances.
- The local profile registry contains `green-commit-only` and
  `blue-mail-triage`. Unknown profiles fail closed. Both restrict the Claude
  session to repository read/edit operations and selected local Git commands;
  lane itself is metadata and consistency validation, not an OS security
  boundary.
- Grant-absent compatibility runs can append repository-local kaizen metrics.
  Granted runs instead require private, durable external metrics with a
  projection descriptor so accepted checkouts remain clean. State Hub
  progress/tool/token events and task closing remain best-effort.
- llm-connect HTTP errors retain only bounded, allowlisted provider diagnosis.

### Packaging and deployment

- The Python package and CLI are version `0.1.0`; Glas and sand-boxer are
  optional sibling runtime dependencies.
- The host deployment includes a user-service claim loop and helpers for
  resolving in-cluster Activity Core, llm-connect, and State Hub services.
- A container image and hardened Kubernetes manifests exist. The Kubernetes
  Deployment currently runs `sleep infinity`; it validates packaging and
  image availability but is not the production claim worker.

## Current evidence and limits

- The historical 2026-07-26 proof exercised a real Claude CLI session and
  commit through the then-current coarse Glas rein contract. The deterministic
  Railiance smoke also proved clone, commit, optional push, and Hub reporting.
- The current profiled queue adapter is deployed at `c633291`. Production run
  `ededc939-266f-473c-8386-ffd3f027f5f0` proved profile/ref preservation,
  governed actor mapping, resolution, normalized failure, and sandbox teardown.
  It failed closed at `session_start` before Claude dispatch or commit because
  executable bwrap reachability, mounted rein runtime, and model egress remain
  with upstream residual `GLAS-IN-0002`.
- Direct legacy agent sessions rely on Claude Code's own tool mediation and
  the host checkout. They are not an OS-level sandbox and do not prove that
  no push/network activity occurred after the run. Unattended mutation now
  takes a process-safe repository lock (ADR-002 / T02).
- Explicitly granted local task files have full repository acceptance and
  clean external metrics. Grant-absent compatibility and profiled queue runs
  still use their prior result contracts because Activity Core carries no
  authoritative repository grant. Durable queue-close replay is also not live.
- The worker is sequential and repository mapping is host configuration. There
  is no multi-worker repository lease, per-tenant process isolation, generic
  credential broker, or tenant onboarding API.
- Freedom Intelligence and Binky approach matching, output formats, event
  names, mailbox paths, and one default push behavior are tenant-specific
  compatibility code. They are implemented capability, but conflict with the
  intended generic-runtime boundary and should not be the pattern for new
  tenants.

## Explicit boundaries

- Scheduling and activity definitions belong to Activity Core.
- Blueprint authoring and improvement loops belong to kaizen-agentic.
- Profile routing and rein selection belong to Glas.
- Sandbox lifecycle and isolation belong to sand-boxer.
- Provider abstraction belongs to llm-connect.
- Durable work history and decisions belong to State Hub; agent memory remains
  in the consuming repository. Granted-run metrics remain external until a
  separately granted kaizen projection commits them to the instance.

## Orientation

- Purpose and target boundaries: `INTENT.md`
- Intent-versus-capability assessment:
  `history/2026-08-23-intent-scope-gap-assessment.md`
- Runtime architecture: `docs/architecture.md`
- Production claim loop: `docs/ops-run-claim-loop.md`
- Deployment: `deploy/README.md`
- Completed work records: `workplans/`