Skip to content

architecture: complete Codectx ambient HUD steering v0 #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
greygoody merged 7 commits into from
Jun 30, 2026
Merged

architecture: complete Codectx ambient HUD steering v0 #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
19ea25c
docs(steering): inventory current Codectx state
greygoody Jun 30, 2026
83f5fe5
docs(steering): define Codectx HUD architecture boundaries
greygoody Jun 30, 2026
84b2558
docs(steering): define Codectx migration gates
greygoody Jun 30, 2026
eea9f43
docs(steering): define Codectx implementation handoffs
greygoody Jun 30, 2026
9aaada2
docs(steering): index accepted Codectx steering package
greygoody Jun 30, 2026
986ba19
docs(steering): record completed Codectx steering state
greygoody Jun 30, 2026
65d0b84
docs(steering): close Codectx steering workcell
greygoody Jun 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 64 additions & 72 deletions docs/implementation-status.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,25 @@

```yaml
canonical_direction: docs/codectx-hud-v0/README.md
current_stage: identity-without-behavior-change
canonical_steering: docs/steering-v0/README.md
current_stage: steering-complete-implementation-not-started
current_product_slice: repository-lens
ambient_compositor: not-implemented
codectx-app: not-implemented
host-runtime-integration: not-implemented
```

The current public implementation remains valid as Codectx's first repository lens and explicit CLI surface. The ambient HUD direction does not imply that a compositor, Codectx App, Orb integration, or continuously hosted runtime already exists.
Step 1 established Codectx as an ambient contextual HUD. Steering workcell #11 has now completed the architecture, migration sequence, and downstream handoffs for Steps 2 and 3.

No compositor, new lens contract, Codectx App, runtime adapter, daemon, database, or ambient surface is implemented by that steering work.

## Current public MVP

Implemented:

- Git repository observation;
- optional default focus plus strict explicit `--focus PATH` handling;
- deterministic `ContextPacket` JSON;
- deterministic `ContextPacket v1` JSON;
- expected, supporting, unexpected, and unclassified paths;
- justfile recipe discovery and definition hashes;
- concise HUD and expanded review output;
Expand All @@ -38,104 +41,93 @@ ContextPacket v1
CLI HUD / JSON / review / handoff
```

## Presentation witness

`fixtures/context-demo/repository` is the public communication fixture. `scripts/demo.sh` commits its baseline, applies expected, supporting, and unexpected changes, and verifies:

- task focus;
- public command discovery;
- hidden-command filtering;
- HUD and review rendering;
- deterministic JSON;
- external-claim authority and unknown freshness;
- byte-identical default handoff output.

## Runseal interoperability

Codectx parses the current closure-record shape while ignoring fields it does not interpret. It imports ID, title, status, requirements, and proof commands.
## Steering outcome

The imported record is always labelled:
The accepted target boundary is:

```text
epistemic_status = external_claim
freshness = unknown
source systems and host events
↓
lenses
↓
host-neutral contribution semantics
↓
compositor
↓
projection
↓
surfaces

host runtime
↓
Codectx App adapter
↓
host-neutral Codectx semantics
```

This proves a useful data boundary without sharing internal crates or letting Codectx declare Runseal truth.

## v0.2 interface policy

The context-first binary forwards historical command names to `codectx-legacy` when both binaries are installed. The compatibility binary is also directly invokable.
Accepted decisions:

The default handoff destination is `.codectx/handoffs/latest.json`. `--output PATH` remains available for explicit integrations in v0.2.
- the current compiler remains the first repository lens;
- `ContextPacket v1` remains frozen and is adapted rather than broadened;
- the compositor owns attention and composition, not source truth or authorization;
- the Codectx App owns host integration and compositor lifecycle;
- derived state is recomputed;
- managed state remains source-owned;
- explicit state has a declared lifetime and requires host acknowledgement for durable persistence;
- contradictory sources remain separately attributed;
- all surfaces consume one projection model;
- Orb is preferred only after an accepted app/runtime contract exists;
- semantic retrieval remains an optional experiment under issue #5.

The default `.codectx/focus.toml` may be absent. An explicitly requested missing focus path is an error.

## Legacy foundation

The original public session prototype remains available through `codectx-legacy`. It contains task/session snapshots, scope accounting, net moves, manually recorded proof status, and stop-readiness views.

Legacy proof recording is an attestation mechanism. It is not state-bound evidence.

The historical `AgentSurface` model is useful migration material for attention state and action affordances. Its completion and proof semantics are not accepted as universal compositor authority.

## Directional mapping

```text
Current repository observer
-> repository lens

ContextPacket v1
-> repository-lens compatibility projection
See:

codectx CLI
-> explicit HUD shell
- [`docs/steering-v0/current-state.md`](steering-v0/current-state.md)
- [`docs/steering-v0/architecture.md`](steering-v0/architecture.md)
- [`docs/steering-v0/migration-plan.md`](steering-v0/migration-plan.md)
- [`docs/steering-v0/downstream-workcells.md`](steering-v0/downstream-workcells.md)

future Codectx App
-> installable host integration and compositor lifecycle manager
## Current compatibility boundary

future compositor
-> host-neutral lens composition and attention engine
The following remain unchanged:

Orb or Codex
-> possible host runtime or device
```
- `ContextPacket v1` shape and semantics;
- CLI commands and output contracts;
- focus-file behavior;
- handoff path and JSON determinism;
- Runseal external-claim treatment;
- legacy command forwarding;
- `.orb/project.toml` product and distribution facts.

This mapping does not authorize code motion or contract changes in Step 1.
Future compositor, lens, move, projection, and Codectx App contracts must be introduced additively and must not silently reinterpret these surfaces.

## Not implemented

- ambient compositor runtime;
- host-neutral lens registration or contribution contracts;
- compositor runtime;
- live subscriptions and projection deltas;
- Codectx App installation or lifecycle;
- Orb or Codex runtime integration;
- continuous event subscriptions;
- projection restoration across bearer or compositor restart;
- persistence restoration across bearer or compositor restart;
- ambient desktop, spatial, or embedded surfaces;
- closure identity, evaluation, or resolution;
- state-bound evidence execution;
- evidence invalidation from source changes;
- generic risk assessment;
- autonomous coding or workflow orchestration;
- repository indexing or RAG;
- daemon, database, or plugin marketplace.

Closure and evidence authority belong to Runseal.
Closure and evidence authority remain external, including Runseal where applicable.

## Step 1 compatibility boundary
## Next authorized implementation work

The following remain unchanged:
The next workcell is the host-neutral compositor and lens vertical slice described in `docs/steering-v0/downstream-workcells.md`.

- `ContextPacket v1` shape and semantics;
- CLI commands and output contracts;
- focus-file behavior;
- handoff path and JSON determinism;
- Runseal external-claim treatment;
- legacy command forwarding;
- `.orb/project.toml` product and distribution facts.
Runtime-hosted integration remains blocked until:

Future compositor, lens, move, and Codectx App contracts must be introduced additively and must not silently reinterpret these surfaces.
1. the host-neutral compositor slice closes;
2. one host exposes accepted app identity, lifecycle, capability, subscription, persistence, and failure contracts.

## Proof
## Current proof

```bash
cargo fmt --all --check
Expand All @@ -145,4 +137,4 @@ cargo run -p codectx-cli --bin codectx -- --help
bash scripts/demo.sh
```

MVP 1 is acceptable only while all five witnesses pass.
The public MVP remains acceptable only while these witnesses pass.
66 changes: 66 additions & 0 deletions docs/steering-v0/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Codectx Ambient HUD Steering v0

## Status

```yaml
workcell: codectx-ambient-hud-steering-v0
tracking_issue: 11
scope: steering-only
step_1_identity: complete
step_2_architecture: complete
step_3_migration_handoffs: complete
implementation: not-started
```

This package completes architecture and migration steering after the accepted Step 1 identity change.

It does not implement a compositor, lens protocol, Codectx App, host adapter, daemon, database, ambient surface, or v2 public schema.

## Package

- [`current-state.md`](current-state.md): inspected implementation and connected-work inventory;
- [`architecture.md`](architecture.md): ownership, dependency, authority, state, contradiction, visibility, and host boundaries;
- [`migration-plan.md`](migration-plan.md): gated Step 2 and Step 3 sequence;
- [`downstream-workcells.md`](downstream-workcells.md): implementation handoffs and stop conditions;
- `closure.md`: final workcell closure and evidence references.

## Accepted steering decisions

1. The current compiler remains Codectx's first repository lens.
2. `ContextPacket v1` remains frozen as the repository-lens compatibility contract.
3. Host-neutral Codectx semantics sit between lenses and surfaces.
4. The compositor owns composition and attention, not domain truth or authorization.
5. The Codectx App owns host integration and compositor lifecycle, not compositor semantics.
6. Derived state is recomputed; managed state remains source-owned; explicit state has declared lifetime.
7. Contradictions remain attributed and visible until an external authority resolves them.
8. Surfaces render one compositor projection rather than inventing separate context models.
9. Orb is the preferred durable host only after its app/runtime contracts are accepted.
10. The CLI remains a compatibility, proof, recovery, and inspection surface after ambient hosting exists.
11. Semantic retrieval remains an optional experiment under issue #5.
12. Implementation proceeds through separate workcells with Orb Eval evidence.

## Dependency direction

```text
sources
↓
lenses
↓
host-neutral contribution and projection semantics
↓
compositor
↓
surfaces

host runtime
↓
Codectx App adapter
↓
host-neutral Codectx semantics
```

## Immediate next state

No implementation should begin from this branch.

The next authorized unit is the host-neutral compositor/lens vertical-slice workcell described in `downstream-workcells.md`. Runtime-hosted integration remains blocked until that slice closes and a host contract passes the selection gate.
Loading
Loading