rein-aharness/workplans/HARNESS-WP-0003-governed-runtime-integrity.md

---
id: HARNESS-WP-0003
type: workplan
title: "Governed runtime integrity and intent convergence"
domain: infotech
repo: rein-aharness
status: active
owner: codex
topic_slug: rein-aharness
priority: high
created: "2026-08-23"
updated: "2026-08-23"
related:
  - REIN-A-0004
  - GLAS-IN-0002
  - ACTIVITY-WP-0032
  - CUST-WP-0065
state_hub_workstream_id: "db086acf-e774-5a8b-8057-941dcbb12582"
---

# HARNESS-WP-0003 — Governed runtime integrity and intent convergence

## Origin

The 2026-08-23 intent–scope assessment found that the deployed v0.1 worker is
a useful sequential Activity Core consumer, but its strongest production
claims exceed its current enforcement and evidence:

1. direct runs accept any `HEAD` change without a repository lock, clean-tree
   gate, changed-path validation, remote-state check, or lease-loss stop;
2. the strategic profile-driven route currently fails closed before dispatch
   on upstream executable sandbox/runtime/egress work in `GLAS-IN-0002`;
3. metrics and best-effort Hub reporting are not an atomic or reconciled part
   of run acceptance;
4. FI/Binky-specific approaches remain inside the shared runtime despite the
   `INTENT.md` prohibition on tenant logic;
5. the active production topology is a host user service while Kubernetes is
   a sleeper placeholder, and optional cross-package contracts can skip in the
   default development environment; and
6. credential and policy enforcement ownership is distributed across the
   execution chain although `INTENT.md` describes this repo as the only holder
   and enforcement point.

Custodian message `c02a26b9-421c-4373-880a-3a17dd89db65` also requests the
missing authoritative `.repo-classification.yaml`. That concrete governance
gap is included in the baseline task rather than left as an untracked side
request.

## Priority and sequencing

- **Critical:** T02–T03 make repository mutation and accepted evidence safe.
- **Critical external gate:** T06 proves the current profiled path only after
  `GLAS-IN-0002` supplies executable reachability/runtime/egress.
- **High:** T05 makes the deployed topology and contract test surface truthful
  before another tenant or worker is added.
- **High:** T04 removes tenant coupling so reuse does not multiply code paths.
- **Enabling:** T01 fixes classification and records the responsibility model
  that all implementation tasks must enforce.

T02, T04, and T05 may proceed in parallel after T01. T03 follows T02. T06 is
the final integration gate and must not manufacture a host-side fallback while
waiting on the sandbox owner.

## Establish the governance and enforcement baseline

```task
id: HARNESS-WP-0003-T01
status: progress
priority: high
state_hub_task_id: "e59d07c8-8976-520d-aee6-d0fe9ef7286b"
```

Review the Custodian classification canon and create the authoritative
`.repo-classification.yaml`, preserving repo identity separately from sector
metadata. Validate it with the fleet tool, commit it, and report the revision
to the Custodian owner request.

In the same task, record an ADR or decision that distinguishes:

- the strategic Activity Core → Glas → rein → sandbox route;
- the transitional profile-absent and issue-core compatibility routes;
- ownership of queue identity, actor identity, tool policy, filesystem and
  network isolation, model routing, credential acquisition/injection/revocation,
  repository acceptance, and durable evidence; and
- which failures must be terminal, retryable, or reconciled.

Do not edit `INTENT.md` merely to match current shortcuts. Either demonstrate
how its “only credential holder / only policy enforcement point” language is
implemented by the governed chain, or amend it through the explicit decision
with sibling-owner acknowledgement.

**Done when:** classification validation passes and the Custodian has the
revision; the responsibility matrix has named owners and evidence at every
boundary; direct/legacy paths have an explicit retirement or support posture;
and T02–T06 can cite stable decisions rather than infer ownership from code.

### Progress — 2026-08-23

- Published the canon-valid owner classification at revision `81f9279`:
  `tooling`, primary sector `agents`, secondary `infotech`. Custodian report:
  message `e92be7f9-f51d-4a40-9eec-adf2132d5c2d`.
- Proposed `docs/adr/ADR-002-governed-execution-responsibility-chain.md` with
  explicit strategic/compatibility routes, responsibility/evidence matrix,
  and terminal/retry/reconciliation semantics. Pending decision:
  `4177b0b7-0b32-4f35-861b-28700531e58c`.
- Requested explicit owner review from Activity Core
  (`4b92da2c-9809-4bbe-be2e-4b1e53e13e13`), Glas
  (`4fe6a048-6ca8-4e52-bb22-e2a82725191c`), sand-boxer
  (`7fd35fd4-b0e1-42f0-bb56-a983a3e25c78`), and llm-connect
  (`c5d1dc62-3dca-4ac8-b3b5-d570d723ceda`). T01 remains `progress` and
  downstream tasks remain `wait` until those reviews are reconciled.
- Glas approved the proposed boundary without edits in message
  `006fa46f-9419-4f61-90ff-0c3b6bc294c1`. Activity Core, sand-boxer, and
  llm-connect acknowledgements remain pending.

## Make each repository run a lease-bound transaction

```task
id: HARNESS-WP-0003-T02
status: wait
priority: high
state_hub_task_id: "47816469-b5c0-5252-8b71-041e65d203fd"
```

Implement one repository transaction guard shared by direct `TaskSpec` runs
and every legacy approach that mutates a checkout. It must:

- key a process-safe lock by canonical repository identity and store lock state
  outside the target checkout;
- capture branch/detached state, `HEAD`, working-tree/index state, relevant
  local remote-tracking refs, and the task/run correlation before mutation;
- refuse unattended production mutation on a dirty or ambiguous baseline,
  while preserving all pre-existing operator changes;
- retain the Activity Core lease for the transaction and make heartbeat/lease
  loss observable to the executor so work cannot silently finish under an
  expired owner; and
- release the repository lock on success, refusal, timeout, signal, adapter
  error, and result-close failure without deleting user data.

Keep production concurrency at one until this guard is proven. Do not add
distributed concurrency merely because a local lock exists.

**Done when:** tests cover concurrent claims for one checkout, distinct repos,
dirty baselines, detached or moved `HEAD`, heartbeat/lease loss, timeout,
signal cleanup, and close failure; a refused run changes neither repository nor
remote refs; and the result carries a bounded transaction identifier and
baseline evidence.

### Preparation — 2026-08-23

Added the production-inert core transaction primitive in
`rein_aharness/repository_transaction.py`. It keys a private external `flock`
by the resolved Git common directory, captures branch/detached `HEAD`, clean or
dirty index/worktree digests, upstream and remote-tracking refs, and exposes a
bounded transaction/baseline evidence envelope. Ten focused tests cover
cross-process same-repo contention, path aliases, distinct repos, dirty/staged/
untracked baselines, detached `HEAD`, private lock metadata, exception cleanup,
and non-repository refusal.

The primitive is intentionally not wired into `runner.py`, legacy approaches,
or the claim loop while ADR-002 still awaits Activity Core, sand-boxer, and
llm-connect acknowledgements. Lease-loss cancellation, moved-`HEAD` acceptance,
timeout/signal integration, and result-close reconciliation remain outstanding;
T02 therefore remains `wait`.

## Verify accepted commits and reconcile metrics/reporting

```task
id: HARNESS-WP-0003-T03
status: wait
priority: high
state_hub_task_id: "bb3ecdc7-7a32-5a9c-999c-857cd484738b"
```

Replace the current `head_after != head_before` success test with explicit
repository acceptance under the T02 transaction. At minimum verify:

- the accepted workload commit descends exactly from the recorded baseline
  according to the declared one-commit or bounded-commit policy;
- changed paths conform to the task/profile grant and Git metadata, hooks, and
  remote configuration were not altered;
- the resulting index and working tree match the declared postcondition;
- no local remote-tracking ref moved unexpectedly and any path that is allowed
  to push has a separate explicit grant and evidence; and
- evidence identifies the accepted commit(s), changed paths, baseline, policy,
  and validation outcome without retaining prompts or provider output.

Decide and implement metrics atomicity: either include repo-owned kaizen
metrics in a declared harness-authored evidence commit or move them to an
external/durable channel with a defined projection back to the instance. A
successful run must not become dirty after commit verification. Add a bounded
outbox or reconciliation mechanism for required State Hub/Activity Core close
evidence; best-effort telemetry may remain non-blocking only when labelled as
such.

**Done when:** adversarial tests reject unrelated commits, extra paths, dirty
post-state, metadata/config edits, and ungranted remote movement; success
leaves the checkout in its declared state; metrics and required completion
evidence survive a temporary Hub/API outage without duplicating the workload
commit; and docs no longer claim checks that the code does not perform.

## Remove tenant logic from the shared runtime

```task
id: HARNESS-WP-0003-T04
status: wait
priority: high
state_hub_task_id: "2eea6721-9379-5904-bf8f-4e794272d74a"
```

Inventory every profile-absent FI/Binky definition and its current owner,
schedule, input/output files, credential lane, completion event, commit/push
behavior, and rollback path. With Activity Core, kaizen-agentic, and tenant
owners, migrate the behavior into versioned profiles plus tenant-owned
blueprints/manifests or separately owned typed capabilities.

Replace substring/label routing and tenant-specific code in the core worker
with a generic, versioned selector. Preserve coexistence only behind an
explicitly dated compatibility flag until each live definition has passing
replacement evidence. In particular, eliminate implicit default push behavior
from shared runtime code; publication must be a named, separately granted
capability.

**Done when:** no new tenant requires editing `approaches.py`; every existing
FI/Binky definition has owner-approved replacement and rollback evidence;
production runs through generic selectors; tenant modules and hard-coded event,
path, and prompt conventions are removed or moved to their owning packages;
and the compatibility flag is disabled before deletion.

### Preparation — 2026-08-23

`docs/legacy-runtime-inventory.md` records the four profile-absent scheduled
definitions and the direct/issue-core compatibility surfaces from current code
and owner files. It identifies inputs, outputs, credentials, completion events,
commit/push behavior, retry posture, rollback material, and migration gates.
This is read-only preparation; T04 remains `wait` until T01 accepts ADR-002.

## Align deployment, recovery, and conformance with the supported runtime

```task
id: HARNESS-WP-0003-T05
status: wait
priority: high
state_hub_task_id: "4e885492-abf9-586b-a049-d8ddb844ecfc"
```

Choose and document the supported production topology from T01. If the host
user service remains authoritative, label the Kubernetes sleeper as packaging
smoke or remove it from runtime claims. If Kubernetes becomes authoritative,
provide real workspace, credential, shutdown, lease, sandbox, and recovery
semantics before cutover.

Make the selected deployment reproducible:

- install pinned, non-accidental Glas/sand-boxer/llm-connect contracts rather
  than relying on mutable sibling editable checkouts;
- preflight bubblewrap/AppArmor and the executable reachability contract when
  the local profile is enabled;
- provide status and recovery checks for claim health, lease expiry, an
  execution crash, an API-close outage, sandbox teardown, and outbox replay;
- run the real cross-package contract tests in CI without silently skipping
  because optional runtime dependencies are absent; and
- define release/version compatibility for the instance manifest, Glas
  contract, profile catalog, Activity Core schema, and deployment artifact.

**Done when:** a clean host or chosen cluster target can reproduce the pinned
worker from documented inputs; readiness fails before claiming if a required
runtime boundary is unavailable; recovery drills leave no held repo lock,
claimed row, orphan sandbox, or lost required evidence; and CI/release gates
exercise the same contract versions as production.

## Re-prove one governed profiled run and close residuals

```task
id: HARNESS-WP-0003-T06
status: wait
priority: high
state_hub_task_id: "0ee6c263-6399-521a-b687-c40b5ee80a26"
```

After T01–T05 and upstream `GLAS-IN-0002` are complete, coordinate one disabled,
bounded Activity Core definition against a disposable controlled repository.
The run must use an explicit versioned profile and attribution refs, cross the
declared sandbox execution boundary, dispatch the real rein/model route, and
produce only the granted commit/evidence.

Capture non-secret evidence for claim/lease ownership, actor, profile, rein,
model, tool profile, sandbox, transaction baseline, accepted commit and changed
paths, metrics/reporting reconciliation, completion state, sandbox teardown,
source-checkout immutability, and absence of leftover lock/task/runtime files.
Exercise one fail-closed negative case under the same deployed artifact. Do not
reuse the withdrawn historical isolation implication from the 2026-07-26
coarse proof.

Before finishing the workplan, hand every actionable leftover to a live owner
record with `origin: residual` and `origin_ref: HARNESS-WP-0003` (or to an already
live canonical record with an explicit acknowledgement).

**Done when:** one current profiled run succeeds end to end, the negative case
fails before ungranted mutation, all cleanup and evidence checks pass, Activity
Core and Glas acknowledge the proof, documentation reflects the deployed
truth, and no residual exists only in prose.

## Overall acceptance

1. Every mutating run is repository-locked, lease-bound, baseline-aware, and
   accepted against explicit commit/path/post-state rules.
2. Required completion and metric evidence is reconciled without dirtying the
   checkout after acceptance or duplicating domain commits.
3. The strategic profile-driven path completes through its declared sandbox;
   no host fallback is introduced.
4. Shared runtime dispatch is tenant-neutral and publication is an explicit
   capability, not an implicit side effect.
5. Credential and enforcement ownership matches a recorded decision and the
   repo has an authoritative validated classification.
6. Production deployment, recovery checks, CI, package versions, and docs all
   describe and exercise the same supported topology.