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`, retains bounded execution evidence, and never falls back to a
  legacy approach after profile refusal or failure. A separately typed queued
  repository grant is parsed strictly and cannot cross a profile-absent route.
- 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, repository transaction/acceptance, external metrics, and durable
  terminal-close delivery—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.
- Profiled terminal closes are written to a private outbox before delivery.
  Pending close-only work replays before another claim; exact Activity Core
  repeats reconcile, permanent machine-distinct conflicts quarantine, and
  operator status/replay commands expose unresolved evidence.
- 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 and profiled Activity Core rows have full
  repository acceptance and clean external metrics. Source compatibility is
  pinned to Activity Core `b63131e` / schema migration `0010`; production must
  deploy that schema/API contract before a granted definition is enabled.
- 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/`

## Owner runtime reuse update — 2026-10-19

The repository includes the credential-free `owner_rehearsal.rehearse` API and
owner renewal support tracked in HARNESS-WP-0008. Reuse these existing paths for
installation verification and bounded attempts; do not introduce a parallel
launcher. Custodian's October 17 native-runtime-install-r3 execution receipt
proves installed artifact `f59959b6…` passes offline rein/Glas/Claude startup,
unchanged full digest and process cleanup. Revision 2's earlier failed rehearsal
is preserved. This has zero model calls and no credential/configuration reads.
Remaining spend-memo lifecycle, owner renewal/pin updates, fresh native approvals
and bounded successful model/tool acceptance remain in HARNESS-WP-0008-T07.
Actual Custodian interactive isolation remains a separate consumer obligation.

## Staged work-record generation — 2026-10-19

The repository explicitly opts into the shared staged work-record generator via
`.generated-work-records.json` and its dedicated `.generated-work-records.mk`.
`make generated-work-records` uses the existing State Hub renderer through the
Custodian adapter, stages only `WORK-RECORDS.md`, and refuses unreconciled
unstaged index edits. `make generated-work-records-check` checks without writes.
The shared commit hook retains its generated-only guard and repository-specific
scanner routing; meaningful source commits regenerate the index before any
configured scan.
Generation performs no Hub calls, commits, pushes, credential access or live
changes. Source inventories and other generated artifacts retain their owners.

## Local orientation brief policy — 2026-10-19

`.custodian-brief.md` is a local, ignored State Hub orientation snapshot. Its
existing bytes remain available for offline session startup; refreshing it does
not require a Git commit. Authored workplans and the generated WORK-RECORDS index
retain their existing source and staged-generation contracts. No runtime or
credential change follows from this repository hygiene policy.