{"schema":"decodex/commit/1","summary":"Land Promote Decodex loop-runtime contract","authority":"XY-851"}

Author: yvette-carlisle

README.md

@@ -16,6 +16,8 @@ Repo-native agent orchestration, upstream Codex radar, and public publishing.
 ## Feature Highlights
 
 - Rust CLI and runtime for repo-native retained coding-agent lanes.
+- Natural-language-first loop-runtime contract with research/decision promotion,
+  internal execution-program state, and normal Linear issue lanes.
 - Native macOS app for Decodex Codex account-pool management.
 - Explicit project registry under `~/.codex/decodex/projects/<service-id>/`.
 - Local operator listener with a dashboard at `/` and `/dashboard`, WebSocket
@@ -333,6 +335,7 @@ structure. For the authoritative layout and ownership map, read
 
 - Product and development overview: this `README.md`
 - Unified documentation router: `docs/index.md`
+- Natural-language loop-runtime contract: `docs/spec/loop-runtime.md`
 - Normative specs: `docs/spec/index.md`
 - Procedural runbooks: `docs/runbook/index.md`
 - Current implementation references: `docs/reference/index.md`

docs/decisions/index.md

@@ -20,6 +20,9 @@ Question this index answers: "why was it designed this way?"
 
 ## Current decisions
 
+- [`natural-language-loop-runtime.md`](./natural-language-loop-runtime.md) records why
+  Decodex keeps execution-graph semantics internal behind a natural-language research
+  and promotion surface.
 - [`decodex-plugin-source.md`](./decodex-plugin-source.md) records why this repository
   owns the canonical Decodex plugin and why generic Playbook guidance should only keep
   portable routing.

docs/decisions/natural-language-loop-runtime.md

@@ -0,0 +1,71 @@
+# Natural-Language Loop Runtime
+
+Status: accepted
+Date: 2026-06-09
+Question: Should Decodex expose execution graphs as the user workflow, or keep graph
+semantics internal behind a natural-language loop runtime?
+Decision: Decodex should be a natural-language-first loop runtime. Research produces a
+latent Loop/Decision Contract, accepted decisions promote into an internal Execution
+Program, and normal Linear issues remain the executable Decodex lanes.
+
+## Context
+
+The current Decodex runtime already owns issue eligibility, retained worktrees,
+tracker writes, validation gates, review handoff, retained review repair, landing,
+closeout, and operator status. A loop-engineering layer needs dependency, ordering,
+conflict-domain, and drift semantics, but exposing those mechanics directly would make
+ordinary use more complicated than the existing Codex conversation workflow.
+
+The intended everyday flow is:
+
+1. The user discusses and researches work in Codex conversation.
+2. Research or design produces a latent decision package.
+3. The user accepts the direction or asks Decodex to arrange or push it forward.
+4. Decodex promotes accepted decisions into internal execution state and normal Linear
+   lanes.
+
+## Decision
+
+Decodex keeps graph semantics backstage.
+
+- The user-facing surface stays natural language.
+- Decodex owns a native Research/Decision stage for Decodex work.
+- Research output is latent until accepted or promoted.
+- Accepted decisions become a Loop/Decision Contract.
+- The loop runtime derives an internal Execution Program with DAG semantics such as
+  objective lineage, dependencies, stage, conflict domain, acceptance criteria, queue
+  intent, ready-node selection, and drift handling.
+- Normal Linear issues remain the executable Decodex lanes.
+- Phase-scoped Codex goals are allowed; one giant "finish issue" goal is not.
+- Goal completion triggers validation or review. It does not prove lane completion.
+- Self-review is cheap smoke. Completion depends on deterministic validation and,
+  where risk warrants, independent fresh-context read-only review.
+- Long unattended execution must stop affected branches for contract or architecture
+  decisions when execution discovers uncovered direction, while continuing independent
+  ready nodes.
+
+The normative contract lives in [`../spec/loop-runtime.md`](../spec/loop-runtime.md).
+
+## Rejected Alternative
+
+The rejected alternative is a user-visible DAG workflow with graph ids, explicit edge
+editing, dry-run/apply/status mechanics, or direct manipulation of Codex goal state as
+the ordinary interface.
+
+That design would expose implementation machinery to users before it creates leverage.
+It would also duplicate the existing Linear lane and Decodex runtime contracts instead
+of letting the runtime use those surfaces as execution adapters.
+
+## Consequences
+
+- Future runtime lanes must treat loop graph state as internal runtime state.
+- Documentation and operator UI should not teach ordinary users to drive Decodex by
+  graph ids or DAG commands.
+- New execution-program code must bridge into existing Linear issue lanes rather than
+  replacing them.
+- Research adapters must preserve an acceptance/promotion boundary before queueing or
+  implementation starts.
+- Loop stop conditions must route to failure attribution, research-contract feedback,
+  architecture review, or manual attention instead of infinite patching.
+- Harness telemetry should improve prompts, skills, validators, issue templates, and
+  loop policy without retroactively changing accepted lane contracts.

docs/index.md

@@ -30,6 +30,9 @@ The split below is by question type, not by human-versus-agent audience.
 
 - Need runtime contracts, invariants, schemas, enums, state machines, or required
   behavior -> `docs/spec/`
+- Need the natural-language-first loop-runtime contract, Research/Decision stage,
+  latent Loop/Decision Contract, internal Execution Program, phase-scoped goals,
+  unattended execution behavior, or loop guardrails -> `docs/spec/loop-runtime.md`
 - Need current Decodex/Codex app-server protocol support
   evidence -> `docs/spec/app-server.md`
 - Need Decodex operator lane-control capability support, including inspect,
@@ -46,6 +49,9 @@ The split below is by question type, not by human-versus-agent audience.
   implementation surface maps -> `docs/reference/`
 - Need durable design rationale, packaging choices, or static-site tradeoffs ->
   `docs/decisions/`
+- Need rationale for keeping execution-graph semantics internal behind a
+  natural-language user surface ->
+  `docs/decisions/natural-language-loop-runtime.md`
 - Need the current Radar, Control Plane, and Publisher capability boundary ->
   `docs/decisions/radar-control-plane-publisher.md`
 - Need Radar raw-artifact retention, archive manifests, or GitHub Release archive
@@ -89,3 +95,5 @@ The split below is by question type, not by human-versus-agent audience.
 - Keep links explicit and stable.
 - Treat `docs/research/` and `docs/plans/` as supporting or historical evidence, not as
   primary authority lanes.
+- Treat research output as latent until accepted or promoted through the loop-runtime
+  contract in `docs/spec/loop-runtime.md`.

docs/reference/operator-control-plane.md

@@ -32,6 +32,10 @@ Decodex currently runs as a local, single-machine control plane:
 - Each project row is scoped by `project_id` and canonical `repo_root`.
 - The project-owned `WORKFLOW.md` remains the execution-policy contract for that
   registered repo.
+- The everyday loop-runtime surface remains Codex conversation. Research/decision
+  promotion and internal Execution Program state are governed by
+  [`../spec/loop-runtime.md`](../spec/loop-runtime.md), not by dashboard graph editing
+  or user-visible DAG commands.
 
 Decodex App is a native shell over the same local runtime and account-pool state. On
 launch it connects to an existing default local listener when one is reachable; if
@@ -442,8 +446,9 @@ rate-limited, or unavailable.
 These directions were discussed but are not part of the current implemented contract:
 
 - Active-lane UI controls for steer, retry, task replacement, or lifecycle mutation.
-- Conflict-domain scheduling for `ui-preview`, `docs`, `tests`, `runtime`, or similar
-  lane classes.
+- User-visible conflict-domain scheduling for `ui-preview`, `docs`, `tests`,
+  `runtime`, or similar lane classes. Future conflict-domain scheduling belongs to the
+  internal Execution Program contract, not to ordinary dashboard graph controls.
 - Demo batch planning that automatically selects two or three small visible issues and
   generates operator observation points.
 - Editing project configuration from the operator UI.
@@ -457,6 +462,7 @@ governing spec first, then update the operator runbook and this reference.
 
 ## Authority Links
 
+- Loop-runtime contract: [`../spec/loop-runtime.md`](../spec/loop-runtime.md)
 - Runtime contract: [`../spec/runtime.md`](../spec/runtime.md)
 - Lane-control capability contract: [`../spec/lane-control.md`](../spec/lane-control.md)
 - Linear execution ledger schema: [`../spec/linear-execution-ledger.md`](../spec/linear-execution-ledger.md)

docs/spec/index.md

@@ -54,6 +54,10 @@ Then keep the body explicit:
 
 ## Current governing specs
 
+- [`loop-runtime.md`](./loop-runtime.md) defines the natural-language-first loop
+  runtime, Decodex-native Research/Decision stage, latent Loop/Decision Contract,
+  internal Execution Program, phase-scoped goals, unattended execution behavior, and
+  loop guardrails.
 - [`runtime.md`](./runtime.md) defines the runtime state model, reconciliation rules, and
   tracker writeback boundaries.
 - [`app-server.md`](./app-server.md) defines the direct Codex `app-server` interaction

docs/spec/lane-control.md

@@ -20,6 +20,11 @@ Lane control is the operator-facing ability to inspect and influence a Decodex-o
 lane without bypassing the runtime lease, tracker, retained-worktree, and review
 contracts.
 
+[`loop-runtime.md`](./loop-runtime.md) owns the natural-language-first research,
+promotion, and internal Execution Program contract. Lane control does not expose that
+program as a user-visible DAG surface. Inspect, steer, interrupt, retained retry, and
+manual attention remain lane controls for already-owned runtime lanes.
+
 The first supported operator-control surface for this rollout is CLI/API. Active-lane
 UI controls are intentionally deferred. The dashboard may show local runtime state for
 observation, but it must not become the primary place where agents or operators author