docs: reconcile scope with verified capability
Some checks failed
ci / validate (push) Has been cancelled
Some checks failed
ci / validate (push) Has been cancelled
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a0233b-178d-7162-b92f-31a31ea8ca9b
This commit is contained in:
parent
5bfc4a6a7d
commit
13aea7ff6f
5 changed files with 288 additions and 58 deletions
155
SCOPE.md
155
SCOPE.md
|
|
@ -2,74 +2,113 @@
|
|||
|
||||
## One-liner
|
||||
|
||||
Primary, profile-driven execution layer routing governed work between concrete
|
||||
agent-harness backends ("reins") while consuming sand-boxer for isolation. See
|
||||
`docs/adr/ADR-001-rein-harness-family.md`.
|
||||
`glas-harness` is a profile-driven control-plane library and CLI that resolves
|
||||
one governed execution request to a concrete rein/model/sandbox constellation,
|
||||
coordinates the outer lifecycle, and returns normalized evidence. It consumes
|
||||
`sand-boxer`; it does not provide a sandbox runtime itself.
|
||||
|
||||
## Core Idea
|
||||
## Verified capabilities
|
||||
|
||||
glas-harness owns the harness contract (`docs/harness-contract.md`:
|
||||
`start_session`/`dispatch_tool`/`end_session`) and the outer loop — profile
|
||||
resolution, rein/model/tool-policy selection, sandbox request/teardown via
|
||||
sand-boxer, actor attribution, and normalized evidence. A rein owns its own
|
||||
inner agentic loop and is invoked through that contract.
|
||||
The repository currently implements:
|
||||
|
||||
Workforce and leadership systems decide *who is responsible for what* and pass
|
||||
assignment, role, duty, goal, and resource-envelope references. Glas decides
|
||||
*how that already-authorized assignment executes*. It does not assign workers,
|
||||
elect leaders, decompose organizational goals, or schedule work.
|
||||
- strict Pydantic models for execution requests, profiles, rein descriptors,
|
||||
lifecycle results, and compact evidence (`src/glas_harness/contract.py`);
|
||||
- deterministic, fail-closed profile and rein-registry resolution, including
|
||||
compatibility, duplicate, status, capability, and inline-secret checks
|
||||
(`src/glas_harness/profiles.py`);
|
||||
- one bounded outer gateway lifecycle: resolve, create sandbox, derive the
|
||||
returned transport, start and dispatch one rein session, summarize, clean up,
|
||||
destroy the sandbox, and report normalized evidence
|
||||
(`src/glas_harness/gateway.py`);
|
||||
- two CLI-backed rein adapters, for `rein-aharness` and `rein-openweights`;
|
||||
- transport enforcement for SSH workspaces and same-host namespace descriptors.
|
||||
Unsupported, incomplete, ambiguous, unavailable, or unauthorized transports
|
||||
fail closed without falling back to the caller checkout;
|
||||
- explicit governed actor validation (`adm`, `agt`, or `atm`) before sandbox
|
||||
creation, keeping queue `worker_id` values outside the actor field;
|
||||
- one invocation channel: the local `glas-harness run` CLI;
|
||||
- a packaged, versioned profile/rein catalog and `glas-harness profiles`
|
||||
validation command; and
|
||||
- compact State Hub progress evidence that excludes prompts, model/tool output,
|
||||
provider bodies, and credentials.
|
||||
|
||||
## In Scope
|
||||
The unit and boundary suite exercises these contracts and the Forgejo workflow
|
||||
installs the package, runs the suite, and validates the packaged catalog.
|
||||
|
||||
- Versioned strict execution request, profile, lifecycle, result, and evidence
|
||||
models plus the `Rein` ABC
|
||||
(`src/glas_harness/contract.py`)
|
||||
- Deterministic harness-profile and rein-registry validation/resolution
|
||||
(`src/glas_harness/profiles.py`)
|
||||
- The gateway that resolves an explicit harness profile, requests a sandbox,
|
||||
runs one task through a rein, verifies, tears down
|
||||
(`src/glas_harness/gateway.py`)
|
||||
- Rein adapters that shell out to each rein's own CLI
|
||||
(`src/glas_harness/reins/`) — currently `rein_aharness.py`,
|
||||
`rein_openweights.py`
|
||||
- The rein registry (`registry/reins/`) and harness profile catalog
|
||||
(`profiles/`)
|
||||
- Compact, non-secret execution evidence and attribution references for State
|
||||
Hub and other audit consumers
|
||||
## Operational capability status
|
||||
|
||||
## Out of Scope
|
||||
| Surface | Current verified status |
|
||||
|---|---|
|
||||
| Profile/catalog resolution | Implemented and CI-validated |
|
||||
| Unknown or invalid profile refusal | Implemented before sandbox creation |
|
||||
| Sandbox create/destroy lifecycle | Implemented; live failure paths prove teardown |
|
||||
| Original-checkout isolation | Enforced by code: it is never a post-create execution fallback |
|
||||
| SSH transport construction | Implemented and unit-tested; no current positive post-hardening live proof |
|
||||
| Same-host bwrap execution | Fail-closed, not operational: consumer `nsenter` is denied and the rein runtime is absent inside the sandbox |
|
||||
| `rein-aharness` adapter | Implemented; current local profile reaches sandbox creation and fails at session start on the bwrap owner boundary |
|
||||
| `rein-openweights` adapter | Implemented; provider credential repair was proven, but current local sandbox execution has the same unresolved owner boundary |
|
||||
| CLI channel | Implemented |
|
||||
| State Hub evidence | Implemented as compact progress evidence, not a complete session/tool audit service |
|
||||
|
||||
- Sandbox provisioning, profiles, placement — owned by `sand-boxer`
|
||||
- A rein's own agentic loop, tool execution, credential acquisition —
|
||||
owned by the rein itself (`rein-aharness`, `rein-openweights`, ...)
|
||||
- Leadership, workforce allocation, role/duty/goal definitions, assignment
|
||||
authority, scheduling, and task sourcing — owned by their domain systems and
|
||||
passed to Glas as references
|
||||
- Scheduling/blueprint sourcing inside the execution layer — stays rein-local
|
||||
(`docs/adr/ADR-003-scheduling-and-blueprint-sourcing-stay-rein-local.md`)
|
||||
- Provider/model catalog authority and inference APIs — owned by providers and
|
||||
`llm-connect`; Glas carries the approved route and resolved identifier
|
||||
- Secrets and credential brokering — credentials remain rein-local and profiles
|
||||
contain route references only
|
||||
- e2e validation, code generation — owned by `wise-validator`,
|
||||
`snuggle-inventor`
|
||||
An `enabled` profile currently means that catalog policy permits selection. It
|
||||
does not prove that its rein executable, credential delivery, network egress,
|
||||
and sandbox transport are operational on a particular host. That semantics is
|
||||
an open governance gap tracked in `GLAS-IN-0005`.
|
||||
|
||||
## Current State
|
||||
## In scope
|
||||
|
||||
The contract and first two reins are implemented. Profiles are executable,
|
||||
versioned runtime inputs; CLI and gateway invocation require an explicit
|
||||
profile; and both rein/model constellations are live-proven with real commits,
|
||||
sandbox cleanup, and the same evidence shape.
|
||||
The CLI channel and Glas-owned State Hub gateway reporting are implemented.
|
||||
- The versioned Glas execution contract and profile/rein catalogs.
|
||||
- Exact profile selection and refusal; no implicit governed rein or model.
|
||||
- Outer execution lifecycle and teardown coordination with sand-boxer.
|
||||
- Reachability-derived command transport and workspace selection.
|
||||
- Rein adapters that translate the stable outer contract to backend CLIs.
|
||||
- Actor attribution and organizational reference propagation without assuming
|
||||
workforce authority.
|
||||
- Direct-caller results and compact, value-safe execution evidence.
|
||||
- Channel interfaces that translate invocations into the same execution
|
||||
request; only the CLI implementation exists today.
|
||||
|
||||
Still outside the current prototype: additional real channel extensions,
|
||||
memory/skills services, subagent delegation, requirements-based profile
|
||||
selection, and workforce-management APIs. Those are not implicit capabilities
|
||||
of the profile router.
|
||||
## Out of scope
|
||||
|
||||
## Getting Oriented
|
||||
- Sandbox profiles, placement, provisioning, owner-mediated execution, and
|
||||
teardown implementation — `sand-boxer`.
|
||||
- A rein's internal agent loop, provider client, tool enforcement, and
|
||||
credential acquisition — the selected rein.
|
||||
- Scheduling, claiming, retries, and task sourcing — `activity-core` or another
|
||||
channel owner.
|
||||
- Roles, duties, assignments, goals, resource envelopes, and authorization —
|
||||
their workforce/leadership systems.
|
||||
- Model-provider authority and inference routing — providers and `llm-connect`.
|
||||
- Secret storage or credential brokering.
|
||||
- End-to-end validation and product code generation — `wise-validator` and
|
||||
`snuggle-inventor`.
|
||||
- State Hub work-record authority.
|
||||
|
||||
- Start with: `INTENT.md`, `docs/adr/ADR-001-rein-harness-family.md`
|
||||
## Intended but not implemented
|
||||
|
||||
The broader vision in `INTENT.md` includes long-lived/resumable sessions,
|
||||
gateway-owned tool catalogs and policy checks, memory and skills services,
|
||||
additional chat/email/MCP channels, cron surfaces, bounded subagent delegation,
|
||||
and richer session/tool audit streams. None is a current repository capability.
|
||||
The present implementation is a bounded execution router over two reins, not
|
||||
yet Coulomb's general-purpose agent harness service.
|
||||
|
||||
## Active gaps
|
||||
|
||||
- `GLAS-WP-0005-T05` / `GLAS-IN-0002`: sand-boxer-owned executable bwrap
|
||||
reachability, rein runtime availability, explicit egress, and credential
|
||||
delivery are required for a positive in-sandbox rein proof.
|
||||
- `GLAS-IN-0003`: grandfather the pre-canon `GLAS-0001` identifiers.
|
||||
- `GLAS-IN-0004`: align the documented ad hoc workplan convention with the
|
||||
identifier canon.
|
||||
- `GLAS-IN-0005`: make profile `enabled` status and operational readiness
|
||||
truthful and testable.
|
||||
|
||||
## Getting oriented
|
||||
|
||||
- Intent and gap assessment: `INTENT.md`,
|
||||
`history/2026-08-23-scope-vs-intent-assessment.md`
|
||||
- Contract: `docs/harness-contract.md`, `docs/execution-profiles.md`
|
||||
- Agent instructions: `AGENTS.md`
|
||||
- Workplans: `workplans/`
|
||||
- Architecture: `docs/adr/ADR-001-rein-harness-family.md`
|
||||
- Live work: `workplans/`, `docs/intakes/residuals.md`
|
||||
- Agent workflow: `AGENTS.md`
|
||||
|
|
|
|||
|
|
@ -15,6 +15,7 @@
|
|||
| workplan | GLAS-WP-0004 | finished | — | workplans/GLAS-WP-0004-versioned-execution-constellation-profiles.md |
|
||||
| workplan | GLAS-WP-0005 | blocked | — | workplans/GLAS-WP-0005-sandbox-boundary-runtime-hardening.md |
|
||||
| workplan | GLAS-WP-0006 | finished | — | workplans/GLAS-WP-0006-consumer-actor-validation.md |
|
||||
| workplan | GLAS-WP-0007 | finished | — | workplans/GLAS-WP-0007-capability-scope-truth.md |
|
||||
| task | GLAS-0001-T01 | done | — | workplans/GLAS-0001-statehub-bootstrap.md |
|
||||
| task | GLAS-0001-T02 | done | — | workplans/GLAS-0001-statehub-bootstrap.md |
|
||||
| task | GLAS-0001-T03 | done | — | workplans/GLAS-0001-statehub-bootstrap.md |
|
||||
|
|
@ -46,7 +47,10 @@
|
|||
| task | GLAS-WP-0005-T04 | done | — | workplans/GLAS-WP-0005-sandbox-boundary-runtime-hardening.md |
|
||||
| task | GLAS-WP-0005-T05 | wait | — | workplans/GLAS-WP-0005-sandbox-boundary-runtime-hardening.md |
|
||||
| task | GLAS-WP-0006-T01 | done | — | workplans/GLAS-WP-0006-consumer-actor-validation.md |
|
||||
| task | GLAS-WP-0007-T01 | done | — | workplans/GLAS-WP-0007-capability-scope-truth.md |
|
||||
| task | GLAS-WP-0007-T02 | done | — | workplans/GLAS-WP-0007-capability-scope-truth.md |
|
||||
| intake | GLAS-IN-0001 | done | blue | docs/intakes/residuals.md |
|
||||
| intake | GLAS-IN-0002 | todo | red | docs/intakes/residuals.md |
|
||||
| intake | GLAS-IN-0003 | todo | green | docs/intakes/residuals.md |
|
||||
| intake | GLAS-IN-0004 | todo | green | docs/intakes/residuals.md |
|
||||
| intake | GLAS-IN-0005 | todo | red | docs/intakes/residuals.md |
|
||||
|
|
|
|||
|
|
@ -139,3 +139,31 @@ description: |
|
|||
assigned and GLAS-WP-0006 is the authoritative record for that work.
|
||||
state_hub_intake_id: "01a02bde-7d1e-7af3-9eba-aecc8f50365c"
|
||||
```
|
||||
|
||||
## GLAS-IN-0005 — Make profile operational readiness explicit
|
||||
|
||||
```yaml
|
||||
id: GLAS-IN-0005
|
||||
kind: intake
|
||||
title: "Separate profile selection enablement from runtime readiness"
|
||||
lane: red
|
||||
status: todo
|
||||
priority: high
|
||||
owner: glas-harness
|
||||
repo: glas-harness
|
||||
origin: residual
|
||||
origin_ref: GLAS-WP-0007
|
||||
description: |
|
||||
The catalog currently labels all three committed profiles enabled when their
|
||||
schemas and rein capabilities are selectable. That status does not prove the
|
||||
selected host can execute the rein inside its sandbox transport. Both local
|
||||
profiles currently fail closed at session_start on the sand-boxer owner-exec
|
||||
boundary, while the remote profile lacks a positive post-hardening proof.
|
||||
|
||||
Define and implement an explicit operational-readiness contract. Decide
|
||||
whether unavailable profiles must be disabled, carry a separate readiness
|
||||
state, or be filtered through a bounded preflight. Catalog and CLI output
|
||||
must not imply runtime executability from schema validation alone. Coordinate
|
||||
with GLAS-IN-0002 for local owner-exec/runtime evidence; do not add a host
|
||||
fallback or claim readiness from lifecycle-only proof.
|
||||
```
|
||||
|
|
|
|||
104
history/2026-08-23-scope-vs-intent-assessment.md
Normal file
104
history/2026-08-23-scope-vs-intent-assessment.md
Normal file
|
|
@ -0,0 +1,104 @@
|
|||
# Scope versus intent assessment — 2026-08-23
|
||||
|
||||
## Purpose
|
||||
|
||||
This assessment compares the verified repository behavior on 2026-08-23 with
|
||||
the target described by `INTENT.md`. It records capability, not aspiration.
|
||||
Catalog validation, old host-side success, or successful sandbox lifecycle are
|
||||
not treated as proof that a rein executed inside its selected sandbox.
|
||||
|
||||
Evidence reviewed:
|
||||
|
||||
- contract, gateway, channel, transport, rein-adapter, profile, and registry
|
||||
source plus the 58-test suite;
|
||||
- `GLAS-WP-0004`, its corrected evidence note, and the residual handoffs;
|
||||
- `GLAS-WP-0005` production fail-closed evidence through sandbox `d750cd5c`;
|
||||
- `GLAS-WP-0006` actor-boundary correction; and
|
||||
- current Forgejo package/test/catalog validation.
|
||||
|
||||
## Executive assessment
|
||||
|
||||
The implemented nucleus matches the narrowest statement in `INTENT.md`: Glas
|
||||
is a strict, versioned execution router that chooses a declared constellation,
|
||||
coordinates sand-boxer lifecycle, invokes one of two concrete reins through a
|
||||
stable adapter shape, and emits normalized evidence.
|
||||
|
||||
It does not yet match the larger claim that Glas is Coulomb's unified agent
|
||||
harness service. The main operational gap is more fundamental than the future
|
||||
feature gaps: neither local profile can currently launch its rein inside the
|
||||
declared bwrap transport. Glas now fails closed at that boundary, which is the
|
||||
correct security behavior but not positive execution capability.
|
||||
|
||||
## Intent pillar assessment
|
||||
|
||||
| Intent pillar | Assessment | Evidence and gap |
|
||||
|---|---|---|
|
||||
| Unified harness API | Partial | Strict request/result and one bounded lifecycle exist. Resume, long-lived sessions, policy transitions, and subagent join semantics do not. |
|
||||
| Harness profile catalog | Implemented as configuration resolution | Versioned catalog and rein compatibility checks are packaged and CI-tested. `enabled` is selection policy, not operational readiness. |
|
||||
| Sand-boxer consumption | Partial and fail-closed | Create/destroy and reachability derivation exist. Local owner-mediated execution/runtime/egress are missing; remote positive execution is unproven after the boundary correction. |
|
||||
| Concrete harness routing | Partial | Two adapters and explicit selection exist. Current local selections cannot reach rein dispatch inside bwrap. |
|
||||
| Tool orchestration and policy | Minimal/delegated | Glas dispatches one opaque `run_task`; the rein owns its loop and tool policy. Glas has no general tool catalog, per-tool policy engine, or explicit elevated path. |
|
||||
| Memory and skills | Not implemented | No memory store, skill service, identity-document lifecycle, or cross-channel persistence exists. |
|
||||
| Channels | Minimal | CLI exists. Chat, email, Slack/Telegram, MCP gateway, and production network service do not. |
|
||||
| Subagent delegation | Not implemented | No spawn/join contract, bounded context delegation, or sub-session lifecycle exists. |
|
||||
| Observability and governance | Partial | Actor/ref attribution, lifecycle outcome, model/profile/rein identifiers, teardown, and value-safe State Hub progress exist. Complete live tool/session event streaming is not a gateway-wide service. |
|
||||
| Workforce separation | Implemented | Organizational references remain opaque and scheduling/assignment authority stays upstream. The production actor mismatch now fails before sandbox creation. |
|
||||
| Sibling boundaries | Implemented architecturally | Glas does not embed sandbox provisioners, validation orchestration, code generation, scheduling, or secret storage. |
|
||||
|
||||
## Corrections to prior scope language
|
||||
|
||||
The previous `SCOPE.md` said profiles were executable and both constellations
|
||||
were live-proven with real commits and sandbox cleanup. Those runs proved
|
||||
profile selection, rein dispatch, provider behavior, commits, evidence shape,
|
||||
and lifecycle cleanup under the implementation that existed then. They did not
|
||||
prove sandbox-contained rein execution: the adapters still invoked host-local
|
||||
CLIs against the caller checkout.
|
||||
|
||||
`GLAS-WP-0005` removed that fallback. A production retry with the corrected
|
||||
actor mapping created bwrap sandbox `d750cd5c`, then failed at session start
|
||||
because direct consumer `nsenter` was not permitted. Destruction and workspace
|
||||
removal succeeded. Current scope therefore claims secure refusal and teardown,
|
||||
not a positive local execution path.
|
||||
|
||||
## Gap register and disposition
|
||||
|
||||
### Operational blockers
|
||||
|
||||
1. **Owner-mediated local execution and runtime delivery — critical.**
|
||||
`GLAS-IN-0002` owns the sand-boxer contract for command execution, mounted or
|
||||
imaged rein runtime, explicit model egress, credential delivery, and teardown
|
||||
evidence. `GLAS-WP-0005-T05` remains waiting on it.
|
||||
2. **Profile readiness semantics — high.** A catalog-valid `enabled` profile is
|
||||
currently presented alongside profiles that cannot dispatch on the deployed
|
||||
runtime. `GLAS-IN-0005` requires an explicit readiness/enablement contract,
|
||||
including whether unproven profiles must be disabled or separately labeled.
|
||||
|
||||
### Record-governance gaps
|
||||
|
||||
3. **Legacy identifiers.** `GLAS-IN-0003` owns exact grandfathering of the
|
||||
stable `GLAS-0001` bootstrap identities.
|
||||
4. **Ad hoc convention mismatch.** `GLAS-IN-0004` owns alignment between the
|
||||
generated `AGENTS.md` convention and Repo Manager's accepted identifier
|
||||
kinds.
|
||||
|
||||
### Roadmap deltas, not current commitments
|
||||
|
||||
Memory/skills, additional channels, resumable sessions, a gateway-owned tool
|
||||
policy system, subagents, and richer audit streams remain intentional future
|
||||
outcomes. They need consumer-backed workplans and acceptance criteria before
|
||||
implementation. This assessment does not silently promote them into a backlog
|
||||
or claim them as capabilities.
|
||||
|
||||
## Recommended sequence
|
||||
|
||||
1. Complete `GLAS-IN-0002` and capture one positive, source-isolated rein run.
|
||||
2. Resolve `GLAS-IN-0005` so catalog output distinguishes selectable schema
|
||||
from deployable runtime capability.
|
||||
3. Reassess whether the remote profile is an operational recovery path or an
|
||||
unproven declaration; retain it only with evidence and owned runtime setup.
|
||||
4. Add broader harness pillars only when a real channel/consumer supplies the
|
||||
boundary and evidence requirements.
|
||||
|
||||
Until steps 1–2 complete, describe Glas as a secure, fail-closed execution
|
||||
router nucleus—not yet the default or unified agent harness service promised by
|
||||
the maturity target in `INTENT.md`.
|
||||
55
workplans/GLAS-WP-0007-capability-scope-truth.md
Normal file
55
workplans/GLAS-WP-0007-capability-scope-truth.md
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
---
|
||||
id: GLAS-WP-0007
|
||||
type: workplan
|
||||
title: "Reconcile declared scope with verified capability"
|
||||
domain: infotech
|
||||
repo: glas-harness
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: capability-scope-truth
|
||||
created: "2026-08-23"
|
||||
updated: "2026-08-23"
|
||||
---
|
||||
|
||||
# Reconcile declared scope with verified capability
|
||||
|
||||
## Replace stale current-capability claims
|
||||
|
||||
```task
|
||||
id: GLAS-WP-0007-T01
|
||||
status: done
|
||||
priority: high
|
||||
```
|
||||
|
||||
Rewrite `SCOPE.md` around verified behavior after the sandbox-boundary
|
||||
correction. Distinguish catalog-valid/selectable profiles from profiles proven
|
||||
operational inside their declared transport, and distinguish implemented
|
||||
gateway/rein adapter behavior from the broader extension platform described by
|
||||
`INTENT.md`.
|
||||
|
||||
**Completed 2026-08-23:** `SCOPE.md` now separates verified contract, catalog,
|
||||
lifecycle, transport, adapter, channel, and evidence behavior from operational
|
||||
runtime readiness. It records the bwrap session-start blocker, the absence of a
|
||||
post-hardening remote proof, and every broader harness capability that remains
|
||||
intent rather than implementation.
|
||||
|
||||
## Assess implemented scope against intent
|
||||
|
||||
```task
|
||||
id: GLAS-WP-0007-T02
|
||||
status: done
|
||||
priority: high
|
||||
```
|
||||
|
||||
Add a dated assessment under `history/` that maps every major `INTENT.md` pillar
|
||||
to evidence, names gaps without converting aspirations into current
|
||||
capabilities, and links every actionable leftover to an existing or new live
|
||||
work record before this workplan finishes.
|
||||
|
||||
**Completed 2026-08-23:**
|
||||
`history/2026-08-23-scope-vs-intent-assessment.md` maps all major intent pillars
|
||||
to current evidence and corrects the prior host-execution proof implication.
|
||||
The sandbox execution gap remains live as `GLAS-IN-0002`; record-governance
|
||||
gaps remain `GLAS-IN-0003/0004`; and the newly exposed selection-versus-runtime
|
||||
readiness gap is registered for handoff as `GLAS-IN-0005`. Broader vision items
|
||||
remain explicit roadmap deltas, not silently created commitments.
|
||||
Loading…
Add table
Add a link
Reference in a new issue