diff --git a/docs/implementation-status.md b/docs/implementation-status.md index c87045d..037aaef 100644 --- a/docs/implementation-status.md +++ b/docs/implementation-status.md @@ -4,14 +4,17 @@ ```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 @@ -19,7 +22,7 @@ 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; @@ -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 @@ -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. \ No newline at end of file diff --git a/docs/steering-v0/README.md b/docs/steering-v0/README.md new file mode 100644 index 0000000..37939f3 --- /dev/null +++ b/docs/steering-v0/README.md @@ -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. \ No newline at end of file diff --git a/docs/steering-v0/architecture.md b/docs/steering-v0/architecture.md new file mode 100644 index 0000000..9c57ea3 --- /dev/null +++ b/docs/steering-v0/architecture.md @@ -0,0 +1,352 @@ +# Codectx Steering v0: Architecture + +## Status + +```yaml +workcell: codectx-ambient-hud-steering-v0 +scope: steering-only +architecture_status: accepted-for-handoff +implementation_status: not-started +``` + +This document defines ownership and dependency direction. It intentionally does not define final Rust types, crate names, serialized schemas, or host-specific APIs. + +## Architectural objective + +Codectx reduces context acquisition from an interaction into perception. + +A host supplies bounded source updates and lifecycle. Lenses translate source material into attributed contributions. The compositor derives one current projection. Surfaces render or expose that projection. Explicit moves change Codectx-owned focus or presentation state through an inspectable boundary. + +```text +source systems and host events + ↓ + lenses + ↓ + lens contributions + ↓ + compositor + ↓ + projection + ↓ + ambient / CLI / machine / review / handoff surfaces +``` + +## Canonical ownership model + +### Codectx core semantics own + +- lens contribution requirements; +- source attribution and source identity; +- origin, freshness, epistemic status, and revision binding; +- projection and attention semantics; +- contradiction preservation and presentation; +- compositor policy semantics; +- surface-independent visibility state; +- explicit Codectx moves and their declared lifetime; +- deterministic recomposition from equivalent inputs and policy. + +### A lens owns + +- adapting one bounded source family; +- validating the source contract it claims to understand; +- emitting attributed contributions; +- declaring source revision, freshness, and epistemic limits; +- refusing unsupported source versions rather than guessing. + +A lens does not own compositor policy, global authority resolution, or source-system truth. + +### The compositor owns + +- accepting compatible lens contributions; +- grouping related contributions without erasing provenance; +- applying accepted priority and visibility policy; +- preserving contradictory contributions; +- deriving attention items; +- collapsing healthy state; +- producing one surface-independent projection; +- applying accepted explicit moves; +- reporting unsupported or incomplete inputs. + +The compositor does not: + +- authorize effects; +- complete work; +- resolve external domain truth; +- mutate source systems; +- invent freshness; +- silently suppress mandatory warnings; +- make a host-specific persistence decision. + +### A surface owns + +- rendering or exposing one projection; +- bounded interaction gestures that become explicit moves; +- presentation adaptation for terminal, machine, desktop, spatial, review, or handoff use. + +A surface does not recompute domain semantics independently or maintain a competing projection model. + +### The Codectx App owns + +- installation into one accepted host; +- compositor lifecycle inside that host; +- registration and configuration of lenses; +- subscription to host events and source updates; +- translation of host capabilities into bounded Codectx inputs; +- delivery of projections to available surfaces; +- routing explicit moves; +- health and diagnostic reporting; +- forwarding persistence requests to the host when policy permits. + +The Codectx App is replaceable host integration. It does not own host-neutral compositor semantics. + +### The host owns + +- process or component lifecycle facilities; +- identity and capability enforcement; +- source subscriptions and event delivery; +- durable storage made available to the app; +- app installation and version management; +- resource limits and isolation; +- durable continuity beyond one compositor instance. + +A host does not gain authority to reinterpret Codectx contracts merely because it executes them. + +## Semantic objects + +The implementation workcell may choose concrete types, but must preserve these distinct semantic roles. + +### Lens contribution + +One attributed statement or bounded group of statements emitted by a lens. + +It must carry enough information to preserve: + +- contributing lens identity and contract version; +- source-system identity; +- source object or scope identity; +- source revision or stable reference when available; +- origin class: derived, managed, or explicit; +- epistemic status; +- freshness or explicit unknown freshness; +- semantic category; +- payload or typed reference; +- visibility constraints, including whether suppression is forbidden; +- evidence or provenance references when present; +- unsupported, incomplete, or stale status. + +A contribution may suggest urgency. It may not unilaterally decide final screen priority unless the accepted policy grants that authority. + +### Attention item + +A compositor-derived item representing relevant change, contradiction, risk, staleness, block, pending decision, or required awareness. + +An attention item must preserve all contributing sources. It cannot turn disagreement into one synthetic fact merely to make the HUD tidier. + +### Projection + +The current surface-independent composed state. + +It contains: + +- active context coordinates; +- visible and collapsed groups; +- attention items; +- source and freshness attribution; +- active explicit moves; +- unsupported or degraded-state notices; +- deterministic ordering under equivalent input and policy. + +A projection is current state, not automatically durable history. + +### Move + +An explicit Codectx-owned request to change focus or presentation state. + +Candidate classes: + +- focus or switch context; +- pin or unpin; +- acknowledge; +- expand or collapse; +- hide when policy permits; +- choose lens visibility; +- declare a deviation reference; +- change active projection coordinates. + +Each move must declare lifetime semantics: + +- transient to one surface interaction; +- compositor-session scoped; +- bearer-session scoped; +- host-persisted until revoked or expired. + +A move requiring durable or shared lifetime must be accepted and persisted by the host. Codectx must not imply durability after an unacknowledged write. + +## State origin and persistence model + +### Derived state + +Examples: Git change classification, command discovery, contradiction detection, attention derived from unexpected scope. + +Rules: + +- recompute from canonical or attributed source inputs; +- do not persist as authoritative history by default; +- cache only with source revision and invalidation identity; +- discard safely when reconstruction is possible. + +### Managed state + +Examples: Orb capability expiry, runtime health, mandatory policy warning, contact notification, Ctudio authority record. + +Rules: + +- source system remains owner; +- Codectx may cache only as an attributed projection input; +- unknown or stale freshness remains visible; +- source updates replace the active projection contribution without rewriting historical source truth. + +### Explicit state + +Examples: focus, pin, acknowledgement, selected visibility, declared deviation. + +Rules: + +- Codectx owns move semantics; +- lifetime is explicit; +- host persistence is required for survival beyond local scope; +- acknowledgement is not equivalent to resolving the underlying condition; +- hiding cannot override mandatory visibility. + +## Authority and contradiction rules + +1. Source attribution is mandatory. +2. Unsupported source versions fail closed at the lens boundary. +3. Missing freshness is represented as unknown, not current. +4. A higher display priority does not imply higher truth authority. +5. Contradictory contributions coexist until an external authority resolves them or policy explicitly chooses a presentation relation. +6. Mandatory warnings cannot be dismissed or hidden unless the source contract and host capability permit it. +7. Acknowledgement changes awareness state, not source truth. +8. A surface cannot omit compositor-declared mandatory visibility. +9. The compositor must report degraded operation when required lenses or inputs are unavailable. +10. Host policy may constrain available lenses and moves, but must remain visible as host policy rather than Codectx fact. + +## Priority and visibility model + +Priority is derived from multiple inputs, not one lens-provided integer. + +The future implementation should support policy over at least: + +- mandatory versus optional visibility; +- severity or urgency; +- relevance to active context; +- freshness; +- change since previous projection; +- contradiction; +- pending decision or action; +- explicit pinning; +- source-authority class; +- surface capacity. + +Healthy, unchanged state should collapse. New, contradictory, mandatory, or decision-blocking state should expand. A low-capacity surface may summarize but cannot erase mandatory source references. + +## Dependency direction + +```text +source adapters / lenses + ↓ +host-neutral Codectx semantics + ↓ +compositor policy and projection + ↓ +surfaces + +host runtime + ↓ capabilities, lifecycle, subscriptions, persistence ports +Codectx App adapter + ↓ +host-neutral Codectx semantics +``` + +Forbidden dependencies: + +- host-neutral compositor depending on Orb, Codex, NATS, a database, or a UI toolkit; +- repository lens depending on compositor host lifecycle; +- surfaces becoming independent sources of projection truth; +- Codectx App embedding domain authority; +- lens contracts importing Runseal, Ctudio, or Orb internal implementation types. + +## Compatibility freeze + +| Surface | Policy before successor proof | +|---|---| +| `ContextPacket v1` | Frozen repository-lens contract | +| focus TOML | Frozen behavior | +| CLI command names | Frozen | +| CLI and JSON output | Frozen for v0.2 consumers | +| handoff artifact | Frozen | +| Runseal import | Remains external claim with unknown freshness | +| legacy protocol | Compatibility-only; no semantic promotion | +| `.orb/project.toml` | Distribution facts only | + +Future semantics require versioned successors or adapters. No field may gain a broader meaning solely through documentation. + +## Host selection gate + +The first production-like Codectx App host is not selected in this steering workcell. + +A host is eligible only when it has accepted contracts for: + +- app/component identity; +- lifecycle start, suspend, resume, stop, and restart; +- bounded capabilities; +- event or subscription delivery; +- app-local state and persistence acknowledgement; +- versioned installation or package identity; +- failure and degraded-state reporting; +- enough isolation to prevent lenses from receiving undeclared authority. + +Orb is the preferred durable target once those contracts exist. Codex may be a local bearer-host target if it exposes equivalent bounded lifecycle and capability contracts. Until then, the Step 2 reference host remains in-process and non-authoritative. + +## Rejected alternatives + +### Make `ContextPacket v1` the universal HUD schema + +Rejected because it is repository-specific and would freeze current concerns into every future lens. + +### Let each surface compose its own context + +Rejected because terminal, machine, and spatial surfaces would diverge in attention and authority semantics. + +### Persist the complete projection as canonical state + +Rejected because most projection state is derived and would become stale duplicated truth. + +### Let lenses set absolute priority + +Rejected because a lens lacks global context and could crowd out mandatory or contradictory information. + +### Put compositor semantics inside Orb + +Rejected because Codectx must remain host-neutral and usable without Orb. + +### Treat acknowledgement as resolution + +Rejected because awareness state and domain truth are different. + +### Add semantic retrieval as a foundational lens now + +Rejected pending issue #5 evaluation. Retrieval may later remain an optional derived lens. + +## Unresolved questions for implementation experiments + +- exact granularity of one contribution versus contribution batch; +- whether policy is compiled configuration, data, or a trait boundary; +- deterministic tie-breaking across equivalent priority items; +- minimal projection-delta protocol for live surfaces; +- acknowledgement identity when multiple bearers share one Orb; +- whether pins are scoped to principal, Orb, bearer, or surface by default; +- degraded behavior when a mandatory managed lens disconnects; +- compatibility strategy for mapping `ContextPacket v1` attention into the new model. + +These questions are bounded experiments for downstream workcells. They do not reopen Codectx product identity or ownership. \ No newline at end of file diff --git a/docs/steering-v0/closure.md b/docs/steering-v0/closure.md new file mode 100644 index 0000000..491c613 --- /dev/null +++ b/docs/steering-v0/closure.md @@ -0,0 +1,57 @@ +# Codectx Ambient HUD Steering v0: Closure + +## Status + +```yaml +workcell_id: codectx-ambient-hud-steering-v0 +tracking_issue: 11 +pull_request: 12 +scope: steering-only +status: complete +implementation_performed: false +``` + +## Completed + +Step 2 produced: + +- current-state inventory; +- ownership and dependency boundaries; +- lens, compositor, projection, attention, move, surface, app, and host semantics; +- state-origin and persistence rules; +- authority, freshness, contradiction, priority, and visibility rules; +- compatibility freeze and unresolved-question register. + +Step 3 produced: + +- gated migration sequence; +- implementation proof and stop conditions; +- ready handoff #13 for the host-neutral compositor slice; +- blocked handoff #14 for runtime-hosted app integration; +- host-selection gate; +- successor and deprecation policy. + +## Compatibility + +No Rust, crate, `ContextPacket v1`, focus, CLI, review, handoff, Runseal, legacy, or Orb-manifest behavior changed. + +## Evidence + +Contribution-only evidence is recorded in `greygoody/orb-eval` at: + +```text +data/contributions/v1/codectx-steering-2026-06-30/ + steering-workcell/codectx-ambient-hud-v0/ +``` + +The bundle records the mission, both steering stages, source snapshots, observations, timeline, artifacts, provenance, self-assessment, and final report. It is historical contribution material, not oracle truth. + +## Not implemented + +No lens protocol, compositor, live subscription, Codectx App, host adapter, persistence layer, ambient surface, semantic retrieval, daemon, database, or public successor schema was implemented. + +## Next state + +Issue #13 may begin after PR #12 is merged and its base revision is recorded. Issue #14 remains blocked until #13 closes and a host passes the accepted runtime-contract gate. + +The steering workcell is complete because implementation can proceed without reopening product identity, ownership, compatibility, or migration order. diff --git a/docs/steering-v0/current-state.md b/docs/steering-v0/current-state.md new file mode 100644 index 0000000..0698c7c --- /dev/null +++ b/docs/steering-v0/current-state.md @@ -0,0 +1,114 @@ +# Codectx Steering v0: Current State + +## Authority + +This document is part of steering workcell `codectx-ambient-hud-steering-v0` tracked by issue #11. + +It records the accepted starting state for architecture and migration decisions. It does not authorize implementation. + +## Inspected canonical sources + +- `README.md` +- `docs/codectx-hud-v0/README.md` +- `docs/codectx-app-v0.md` +- `docs/context-packet-v1.md` +- `docs/implementation-status.md` +- accepted v0.2 release work in PR #4 +- Orb distribution-contract work in PR #8 +- semantic-retrieval investigation in issue #5 +- ambient-HUD direction in PR #9 +- Orb system direction and steering work in `greygoody/orb` + +## Implemented product slice + +The current implementation is a deterministic repository lens with explicit surfaces: + +```text +Git repository, focus file, justfile, imported external record + ↓ + ContextPacket v1 + ↓ + CLI HUD / JSON / review / handoff +``` + +Implemented and accepted: + +- Git root, branch, revision, dirty state, and baseline-relative observation; +- optional default focus and strict explicit focus-path handling; +- expected, supporting, unexpected, and unclassified change grouping; +- public command discovery with definition hashes; +- deterministic `ContextPacket v1`; +- concise CLI HUD, JSON, reviewer, and durable handoff surfaces; +- Runseal imports retained as external claims with unknown freshness; +- preserved `codectx-legacy` session runtime and compatibility forwarding; +- fixture-backed public demo and Rust proof commands. + +## Current implementation boundaries + +| Surface | Current authority | Steering disposition | +|---|---|---| +| Git observation | Git and repository state | Preserve as repository-lens source | +| `.codectx/focus.toml` | Explicit local focus declaration | Preserve as explicit repository-lens input | +| `ContextPacket v1` | Repository-lens compatibility projection | Freeze; adapt into future lens contribution | +| `codectx` CLI | Explicit HUD shell | Preserve as compatibility and proof surface | +| `codectx --json` | Deterministic machine projection | Preserve; do not redefine as universal HUD schema | +| `codectx review` | Expanded repository review surface | Preserve | +| `codectx handoff` | Durable repository projection artifact | Preserve | +| `codectx-legacy` | Historical session/event compatibility runtime | Preserve; do not promote its completion semantics | +| Runseal import | External claim only | Preserve source authority and unknown freshness | +| `.orb/project.toml` | Product/distribution facts | Preserve; not an Orb-native app package | +| semantic retrieval issue #5 | Unaccepted experiment | Keep optional and external until evaluated | + +## Directional concepts already accepted + +Step 1 established these concepts without behavior changes: + +- Codectx: ambient context and attention system; +- Lens: bounded context provider; +- Compositor: host-neutral composition and attention engine; +- Projection: current composed visible state; +- Attention item: context requiring awareness; +- Move: explicit structured change to Codectx focus or presentation state; +- Surface: renderer or interaction endpoint; +- Codectx App: installable host integration and compositor lifecycle component; +- Host runtime or device: provider of lifecycle, subscriptions, identity, capabilities, delivery, and durable continuity. + +## Connected-system ownership + +| System | Owns | Does not become | +|---|---|---| +| Orb | durable identity, relationships, apps, capabilities, communication, commitments, and history | Codectx compositor | +| Codex or another bearer runtime | execution and worker lifecycle | durable Codectx truth by default | +| Runseal | obligation, evidence, resolution, regression, and closure semantics | Codectx lens implementation | +| Ctudio domains | domain-specific authority and design rules | compositor policy owner | +| Git | repository and revision truth | attention or presentation engine | +| Codectx | bounded projections, composition, attention, source attribution, surfaces, and explicit moves | domain authority, completion authority, or effect authorizer | + +## Missing architecture + +The following are direction only and must not be described as implemented: + +- host-neutral lens contribution semantics; +- compositor input, policy, and projection semantics; +- contradiction and mandatory-visibility behavior; +- persistence ownership across derived, managed, and explicit state; +- live subscriptions and recomposition; +- Codectx App installation and lifecycle; +- Orb, Codex, or other runtime adapters; +- ambient surfaces; +- continuity after compositor or bearer replacement. + +## Contradictions to avoid + +1. `ContextPacket v1` cannot simultaneously remain a repository-lens contract and become the universal compositor protocol. +2. Codectx cannot preserve source authority while allowing lenses to silently promote claims into facts. +3. A host cannot own Codectx semantics merely because it runs the compositor. +4. Codectx cannot be ambient if every update requires the worker to invoke a command and reconstruct context manually. +5. Derived projection state should not become durable history merely because persistence is available. +6. Explicit moves should not disappear on restart when their declared lifetime requires continuity. +7. `AgentSurface` stop-readiness and proof fields cannot become universal HUD authority without importing obsolete completion semantics. +8. Orb must not be selected as the first host until its app/runtime contract is accepted; naming it early is not an interface. + +## Starting conclusion + +The existing implementation is a valid, proven repository lens. Steering must add architecture above it through adapters and versioned successors while keeping current consumers operational. \ No newline at end of file diff --git a/docs/steering-v0/downstream-workcells.md b/docs/steering-v0/downstream-workcells.md new file mode 100644 index 0000000..81151c8 --- /dev/null +++ b/docs/steering-v0/downstream-workcells.md @@ -0,0 +1,176 @@ +# Codectx Steering v0: Downstream Workcells + +These handoffs are produced by steering workcell #11. They authorize no implementation until created as separate issues with an explicit accepted base revision. + +## Handoff A: host-neutral compositor and lens seam + +### Proposed title + +```text +Implement host-neutral Codectx compositor vertical slice +``` + +### Mission + +Implement the smallest deterministic, host-neutral compositor slice that adapts the current repository lens, accepts one synthetic managed lens, applies one explicit move, and emits one surface-independent projection. + +### Prerequisites + +- steering package merged; +- `ContextPacket v1` compatibility proof passing; +- base branch and ownership unambiguous; +- no unresolved contradiction in source, origin, freshness, or mandatory-visibility semantics. + +### Required scope + +- versioned internal or public experimental contracts for lens contribution, attention item, projection, and move; +- validation that fails closed on unsupported versions; +- adapter from `ContextPacket v1` into a repository-lens contribution; +- one synthetic managed-runtime lens fixture; +- deterministic compositor policy sufficient for the accepted scenarios; +- one in-process reference host; +- machine-readable projection trace; +- compatibility tests for current CLI and JSON output. + +### Required scenarios + +1. healthy repository and runtime state collapses; +2. unexpected repository change creates attention; +3. managed urgent warning becomes visible; +4. contradictory repository and managed contributions remain separately attributed; +5. acknowledgement changes attention state, not source truth; +6. compositor recreation recomputes derived state; +7. unsupported contribution version fails closed; +8. missing mandatory lens produces degraded state. + +### Non-goals + +- Orb or Codex integration; +- Codectx App package; +- daemon, database, network, or plugin marketplace; +- durable persistence beyond test fixtures; +- semantic retrieval; +- generalized policy language; +- new visual UI; +- changing current v1 surfaces. + +### Required proof + +- formatting, linting, unit tests, integration tests; +- current `just check` witnesses remain green; +- deterministic repeated fixture run; +- exact projection trace committed or attached; +- changed-path and dependency-boundary report; +- evidence contribution recorded in Orb Eval. + +### Stop conditions + +Stop and report when: + +- implementation requires a host-specific dependency; +- `ContextPacket v1` must change; +- mandatory visibility cannot be represented without inventing authority; +- contradiction handling requires domain resolution; +- the current CLI compatibility surface regresses. + +### Completion + +The workcell closes when one coherent in-process slice passes all scenarios and yields a reviewable contract for host integration. + +--- + +## Handoff B: runtime-hosted Codectx App and ambient continuity proof + +### Proposed title + +```text +Integrate Codectx App with an accepted host and prove ambient continuity +``` + +### Status + +```yaml +state: blocked +blocked_by: + - host-neutral compositor vertical slice + - accepted host runtime/app contract +``` + +### Mission + +Install and supervise Codectx through one accepted host runtime, maintain a live projection from at least two lenses, process one explicit move, and prove correct state behavior across compositor or bearer restart. + +### Host-selection decision required + +Before implementation, record: + +- candidate hosts inspected; +- app identity and lifecycle contract; +- capability boundary; +- event/subscription model; +- app-local state and persistence acknowledgement; +- failure and resource model; +- selected host and rejected alternatives. + +Orb is preferred only after these contracts are accepted. Codex is eligible only if it exposes equivalent bounded integration. No host is selected by this steering package. + +### Required scope + +- one host-specific Codectx App adapter; +- compositor lifecycle management; +- bounded lens registration and subscriptions; +- projection delivery to one continuously subscribed or ambient surface; +- explicit move routing; +- persistence of one eligible explicit state item; +- restart and degraded-state handling; +- version and capability rejection tests; +- complete execution trace. + +### Required scenario + +1. host installs and starts the Codectx App; +2. repository and managed lenses connect; +3. healthy state collapses; +4. urgent or contradictory update appears without manual query; +5. one explicit move is accepted; +6. bearer or compositor restarts; +7. eligible explicit state is restored; +8. derived state is recomputed; +9. managed source state is re-observed rather than treated as Codectx-owned history; +10. current v1 CLI remains usable as recovery and inspection surface. + +### Non-goals + +- multiple production hosts; +- distributed projection federation; +- social/contact implementation inside Codectx; +- general-purpose app marketplace; +- rewriting Orb or Codex runtime architecture; +- production deployment; +- making Codectx authoritative for source-system truth. + +### Required proof + +- exact selected-host contract and version; +- capability matrix; +- lifecycle trace; +- subscription/update trace; +- restart/continuity trace; +- stale and degraded-state trace; +- compatibility proof for existing CLI and packets; +- evidence contribution recorded in Orb Eval. + +### Stop conditions + +Stop and report when: + +- host contracts are unstable or implicit; +- durable writes cannot be acknowledged; +- host requires compositor semantics to move into the adapter; +- undeclared capabilities are required; +- source freshness cannot be preserved; +- restart proof requires persisting derived projection as authority. + +### Completion + +The workcell closes only when Codectx is continuously available through one real host while preserving host neutrality, source authority, compatibility, and declared state lifetimes. \ No newline at end of file diff --git a/docs/steering-v0/migration-plan.md b/docs/steering-v0/migration-plan.md new file mode 100644 index 0000000..3abafec --- /dev/null +++ b/docs/steering-v0/migration-plan.md @@ -0,0 +1,214 @@ +# Codectx Steering v0: Migration Plan + +## Purpose + +This plan converts the accepted ambient-HUD direction into safe implementation stages. It is a steering artifact, not implementation authorization by itself. + +## Stage map + +```text +Step 1: identity and compatibility direction complete + ↓ +Step 2A: host-neutral semantic contracts future workcell + ↓ +Step 2B: deterministic in-process compositor proof same or follow-on workcell + ↓ +Step 3A: Codectx App host adapter blocked on host contract + ↓ +Step 3B: ambient live-projection continuity proof blocked on 3A +``` + +The earlier shorthand of only “Step 2” and “Step 3” remains valid at product level. The A/B gates prevent each step from becoming one oversized branch containing contracts, runtime integration, persistence, and UI experiments because apparently branches also dream of empire. + +## Step 2A: host-neutral semantic contracts + +### Mission + +Introduce the smallest accepted contract model for lens contributions, compositor policy inputs, projections, attention items, moves, and surfaces without host-specific dependencies. + +### Required inputs + +- accepted steering architecture; +- frozen `ContextPacket v1`; +- representative repository-lens fixture; +- at least one synthetic managed source fixture; +- unresolved-question register from steering. + +### Allowed changes + +- versioned host-neutral domain types; +- deterministic validation; +- repository-lens adapter from `ContextPacket v1`; +- fixtures and tests; +- architecture notes narrowed by implementation evidence. + +### Forbidden changes + +- Orb, Codex, NATS, database, or UI framework dependencies; +- changing `ContextPacket v1`; +- app installation or runtime lifecycle; +- live subscriptions; +- durable persistence; +- semantic retrieval; +- domain-specific authority logic. + +### Proof gate + +- unsupported contribution versions fail closed; +- source, origin, freshness, epistemic status, and mandatory visibility remain distinguishable; +- repository packet adaptation is deterministic; +- contradictory contributions remain separately attributed; +- derived, managed, and explicit state cannot be silently interchanged; +- no existing CLI or packet behavior changes. + +### Stop conditions + +Stop when a proposed contract requires inventing source authority, silently broadens v1 semantics, or depends on a specific host. + +## Step 2B: deterministic in-process compositor proof + +### Mission + +Prove the accepted semantics in one in-process reference host before selecting Orb or Codex integration. + +### Required scenario + +Compose at least: + +1. the existing repository lens; +2. one bounded synthetic managed-runtime lens; +3. one explicit move. + +The proof must demonstrate: + +- healthy state collapses; +- new or urgent state expands; +- mandatory visibility survives surface capacity limits; +- contradictory inputs remain visible and attributed; +- acknowledgement changes attention state but not source truth; +- equivalent inputs and policy produce deterministic projections; +- projection state can be discarded and recomputed; +- only declared explicit state is eligible for persistence. + +### Reference host boundary + +The reference host is a test harness or in-process executable. It is not a Codectx App package and does not establish production runtime ownership. + +### Proof gate + +- no network or database required; +- compositor has no host-specific dependency; +- CLI compatibility proof still passes; +- repository lens adapter preserves v1 output semantics; +- failure and degraded-state projection are inspectable. + +## Step 3A: Codectx App host adapter + +### Host-selection gate + +Do not start until one host has accepted contracts for: + +- app identity and versioning; +- lifecycle; +- capability routing; +- event delivery or subscriptions; +- app-local state; +- persistence acknowledgement; +- resource and failure reporting. + +Preferred order: + +1. Orb when its runtime/app contracts are accepted; +2. Codex when it exposes an equivalent bounded integration surface; +3. another reference runtime only when it proves the same boundaries. + +Selection must be recorded as an architecture decision with rejected alternatives. “It is nearby” is not a runtime contract. + +### Mission + +Implement the Codectx App as a thin host adapter around the already proven host-neutral compositor. + +### Required behaviors + +- start, suspend, resume, restart, and stop compositor lifecycle; +- register bounded lenses; +- translate host events without importing host internals into core semantics; +- deliver projections to at least one surface; +- route explicit moves; +- request persistence for eligible explicit state; +- expose health and degraded state; +- reject undeclared capabilities. + +### Forbidden changes + +- moving compositor policy into the host adapter; +- making host events authoritative merely because they arrived; +- persisting derived state as durable truth; +- adding arbitrary source access to simplify integration; +- redefining Orb or Codex ownership. + +## Step 3B: ambient continuity proof + +### Mission + +Demonstrate that Codectx behaves like an always-present HUD rather than a command the worker must remember to run. + +### Required scenario + +1. host starts Codectx App and compositor; +2. repository lens reports healthy state and projection collapses; +3. managed lens reports an urgent or contradictory change; +4. projection updates without manual navigation; +5. worker or bearer issues one explicit move such as pin or acknowledge; +6. compositor or bearer restarts; +7. host restores only state whose declared lifetime requires continuity; +8. derived state is recomputed from sources; +9. urgent state remains visible until source or accepted policy changes; +10. projection is available through an ambient or continuously subscribed surface. + +### Closure gate + +- update latency and ordering are measured; +- dropped or stale source updates produce degraded-state evidence; +- host restart does not transform acknowledgement into resolution; +- unsupported lens/app versions fail closed; +- no existing v1 consumer breaks; +- the complete trace is inspectable. + +## Current-work disposition + +| Current work | Disposition | +|---|---| +| repository observer and packet compiler | preserve; adapt as first lens | +| CLI HUD, JSON, review, handoff | preserve as explicit compatibility surfaces | +| `codectx-legacy` | freeze as compatibility runtime | +| historical `AgentSurface` | mine for presentation concepts only; no semantic promotion | +| Runseal import | preserve external-claim boundary | +| `.orb/project.toml` | preserve product/distribution contract; successor app packaging is separate | +| semantic retrieval issue #5 | keep experimental and non-blocking | +| Step 1 HUD docs | superseded only by versioned accepted steering docs, not deleted | + +## Successor and deprecation policy + +1. Existing v1 contracts remain readable for at least one accepted successor cycle. +2. Successors use new kind/version identities rather than changing v1 field meaning. +3. Adapters preserve attribution and unknown states; they do not manufacture missing semantics. +4. Deprecation requires a consumer inventory, migration witness, and removal issue. +5. The CLI remains a proof and recovery surface even after ambient hosting exists. +6. Legacy session behavior is removed only after explicit replacement and migration evidence. + +## Evidence policy + +Each implementation workcell must record: + +- verified base and head revisions; +- accepted architecture inputs; +- changed paths; +- exact commands and outcomes; +- scenario traces; +- compatibility witnesses; +- rejected alternatives and contradictions; +- remaining unknowns; +- proof that no external source authority was silently imported. + +Evidence belongs in `greygoody/orb-eval` as contribution-only material until separately curated. \ No newline at end of file