diff --git a/README.md b/README.md index 58dc1031c..36a69c297 100644 --- a/README.md +++ b/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//`. - 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` diff --git a/docs/decisions/index.md b/docs/decisions/index.md index 504a963a5..77ed34b12 100644 --- a/docs/decisions/index.md +++ b/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. diff --git a/docs/decisions/natural-language-loop-runtime.md b/docs/decisions/natural-language-loop-runtime.md new file mode 100644 index 000000000..8f4a48855 --- /dev/null +++ b/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. diff --git a/docs/index.md b/docs/index.md index 9418ef1ef..cec4e98b3 100644 --- a/docs/index.md +++ b/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`. diff --git a/docs/reference/operator-control-plane.md b/docs/reference/operator-control-plane.md index 1da21fb7f..a4cab474b 100644 --- a/docs/reference/operator-control-plane.md +++ b/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) diff --git a/docs/spec/index.md b/docs/spec/index.md index 8a6965e5d..75e6aa418 100644 --- a/docs/spec/index.md +++ b/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 diff --git a/docs/spec/lane-control.md b/docs/spec/lane-control.md index 0b951f26e..62bd5aaae 100644 --- a/docs/spec/lane-control.md +++ b/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 diff --git a/docs/spec/loop-runtime.md b/docs/spec/loop-runtime.md new file mode 100644 index 000000000..9475cd821 --- /dev/null +++ b/docs/spec/loop-runtime.md @@ -0,0 +1,267 @@ +# Loop Runtime Specification + +Purpose: Define the natural-language-first Decodex loop-runtime contract that sits +above individual issue lanes. +Status: normative +Read this when: You are implementing or reviewing Decodex-native research, +decision promotion, internal execution planning, phase-scoped Codex goals, unattended +loop behavior, or loop guardrails. +Not this document: The issue-lane state machine, low-level `app-server` protocol, +post-`In Review` phases, operator lane-control commands, or the concrete research +method. +Defines: The user surface, Research/Decision stage, latent Loop/Decision Contract, +internal Execution Program, promotion boundary, phase-scoped goal rules, validation +and review boundary, unattended execution behavior, loop stop conditions, and harness +improvement loop. + +## Scope + +Decodex is a natural-language-first loop runtime. The everyday user surface is Codex +conversation, not a graph editor, DAG command set, issue-batch command language, or +Codex goal-control surface. + +Ordinary user intents are conversational: + +- `research X` starts a research/design pass and may produce a latent execution plan. +- `arrange this`, `push this forward`, or equivalent natural-language follow-up + promotes accepted decisions into executable work. +- Users do not need to manipulate graph ids, DAG commands, dry-run/apply/status + mechanics, queue internals, or Codex goal internals for ordinary Decodex use. + +This document defines the target loop-runtime contract. Current lower-level runtime +behavior remains governed by [`runtime.md`](./runtime.md), [`lane-control.md`](./lane-control.md), +[`post-review-lifecycle.md`](./post-review-lifecycle.md), and +[`review-orchestration.md`](./review-orchestration.md). + +## Authority Model + +The loop runtime has three authority layers: + +| Layer | Authority | +| --- | --- | +| Conversation | Natural-language user intent, acceptance, rejection, and promotion decisions. | +| Loop runtime | Research/Decision records, accepted Loop/Decision Contracts, internal Execution Programs, ready-node selection, drift handling, stop attribution, and harness telemetry. | +| Lane runtime | Normal Decodex issue lanes, app-server attempts, validation gates, review handoff, retained repair, landing, closeout, and cleanup. | + +Research output is latent until accepted or promoted. A research artifact, plan draft, +or proposed issue split must not by itself enqueue work, create authoritative +dependencies, set goals, mutate tracker state, or start implementation. + +After acceptance or promotion, the accepted Loop/Decision Contract, shortened to +Decision Contract in this spec, becomes loop-runtime authority. The runtime may then +shape or update normal Linear issues and queue intent, but executable work still runs +through the lane runtime contract. + +## Research/Decision Stage + +Decodex should own a native Research/Decision stage for Decodex work. That stage may +eventually replace the external research skill for Decodex planning, but the current +external `docs/research/` artifact lane remains supporting evidence only until a +Decodex-native adapter is implemented. + +A Research/Decision stage may produce a latent Loop/Decision Contract with: + +- objective and objective lineage +- evidence, constraints, assumptions, and rejected alternatives +- proposed decisions and open direction questions +- non-goals and scope boundaries +- acceptance criteria and validation expectations +- dependency and blocker model +- conflict domains such as `docs`, `runtime`, `site`, `tests`, or a more specific + repository-owned domain +- proposed issue split and queue intent +- risk notes that decide whether independent review is required + +The latent contract is a candidate decision package. It becomes authoritative only +after the user or an accepted runtime policy promotes it. + +## Promotion Boundary + +Promotion is the boundary between design and execution authority. + +Promotion requires one of these accepted signals: + +- explicit user acceptance in conversation +- a natural-language follow-up that clearly asks Decodex to arrange, queue, or push + the accepted work forward +- a future runtime-owned policy that is itself backed by an already accepted Decision + Contract + +Promotion must preserve what was accepted. If the runtime discovers that the research +artifact contains unresolved direction, contradictory requirements, or missing +acceptance criteria, it must request more decision authority instead of starting +execution. + +Promotion may create or update normal Linear issues, dependencies, labels, or queue +intent. It must not expose an ordinary user workflow that depends on graph ids, +manual DAG edge editing, or hidden Codex goal state. + +## Internal Execution Program + +An Execution Program is internal loop-runtime state derived from accepted Decision +Contracts. It may use DAG semantics, but the graph is backstage state rather than the +user-facing workflow. + +Each program node should carry: + +- objective lineage back to the accepted Decision Contract +- executable stage such as `decision`, `issue_shaping`, `queued`, `running`, + `validation_repair`, `review_wait`, `review_repair`, `landing`, `closeout`, + `blocked`, or `done` +- dependencies and blocker references +- conflict domain +- acceptance criteria and validation gates +- queue intent and service id +- ready-node selection reason +- drift status against the accepted contract +- linked Linear issue identity when the node becomes executable + +Normal Linear issues remain the executable Decodex lanes. A program node may become +eligible only by creating or updating a normal issue with enough natural-language +briefing for generic dispatch and by applying the configured queue policy. The +Execution Program does not replace Linear as the team-visible backlog or the runtime +lane model. + +Ready-node selection is runtime-owned. It should choose nodes whose dependencies are +done, whose conflict domains are available, whose acceptance criteria are concrete, +and whose queue intent is accepted. If those facts are missing or stale, the node is +not ready. + +## Drift Handling + +The loop runtime must compare active execution against the accepted Decision Contract. +Drift includes: + +- an issue whose scope no longer matches the accepted node objective +- a dependency or conflict-domain change that changes execution order +- new evidence that invalidates a settled decision +- implementation needs that require a direction decision not present in the contract +- review or validation findings that imply the accepted architecture is wrong + +Small implementation discoveries may update local execution evidence when they do not +change accepted direction. Direction drift must pause the affected node and request a +research-contract or architecture decision. Dependent nodes must wait. Independent +ready nodes may continue. + +## Phase-Scoped Codex Goals + +Codex goals used by Decodex lanes must be phase-scoped. Do not set one giant goal such +as "finish the issue" for an entire lane. + +Supported goal scopes are examples of the required shape: + +| Goal phase | Meaning | +| --- | --- | +| `implement_to_validation_ready` | Produce the smallest coherent implementation or docs change that is ready for the repo gate. | +| `repair_validation_failures` | Fix concrete canonicalize or verify failures and rerun the same gate. | +| `repair_accepted_review_findings` | Repair validated review findings for the current head without widening scope. | +| `handoff_evidence` | Prepare the PR-backed handoff, evidence summary, and terminal tracker signal after validation and review are satisfied. | + +Goal completion is a trigger for the next validation or review step. It is not proof +that the lane is complete, reviewed, merged, landed, or closed. Lane completion still +requires the deterministic validation, review, PR handoff, manual-attention, landing, +closeout, and terminal-finalization contracts owned by the lower-level specs. + +## Validation And Review + +Self-review is a cheap smoke check. It can catch obvious mistakes, missing edits, or +local reasoning gaps, but it is not sufficient completion evidence by itself. + +Completion needs deterministic validation. For repository lanes, the registered +project `WORKFLOW.md` defines the canonicalize and verify commands, and +[`runtime.md`](./runtime.md) defines how repo-gate failures are classified. + +When risk warrants review beyond self-review, use an independent fresh-context +read-only review pass. This pass is distinct from in-thread self-review: + +- it reads the current `HEAD`, diff, requirements, and relevant specs from scratch +- it does not rely on the implementer's memory of the change +- it stays read-only while producing findings +- it checks intended behavior, regression risk, tests, docs/config drift, migration + fallout, and operator-facing fallout +- candidate findings must be validated before repair work changes the lane + +The review orchestration contract, including internal/external review modes and +review-stop classes, is defined by [`review-orchestration.md`](./review-orchestration.md). + +## Unattended Execution + +Long unattended execution requires settled direction before execution starts. The +runtime should not rely on an agent to invent product or architecture direction while +draining a queue. + +If execution discovers uncovered direction: + +1. Pause the affected node or branch. +2. Preserve the concrete question, evidence, and blocked acceptance criterion. +3. Route the node to a research-contract or architecture-review stop. +4. Continue other ready nodes whose dependencies and conflict domains are unaffected. + +The affected lane should use `manual_attention` or the later accepted loop-runtime +stop surface when it cannot safely continue from the current contract. It must not +silently broaden scope, rewrite the accepted contract, or treat an unaccepted research +idea as execution authority. + +## Loop Guardrails + +The loop runtime must stop bounded churn instead of patching indefinitely. + +Stop conditions include: + +- three repeated failures with the same validation command and materially same root + cause after attempted repair +- three consecutive attempts that produce no effective diff, no new validation + evidence, and no new decision evidence +- review repair churn that reaches the stop rules in + [`review-orchestration.md`](./review-orchestration.md) +- repeated dependency blockers where the blocked node cannot make progress and the + dependency state is not changing +- uncovered contract questions that affect accepted direction or acceptance criteria +- contradictory tracker, PR, branch, or runtime ownership evidence that cannot be + resolved without guessing + +Stop attribution must preserve the reason instead of collapsing failures into a +generic retry bucket. Normalized outcomes include: + +| Outcome | Use when | +| --- | --- | +| `validation_failure_repeated` | The same validation class repeats after bounded repair. | +| `no_effective_diff` | Repeated attempts do not change the head, evidence, or decision state. | +| `review_policy_exhausted` | Review findings exceed the accepted repair convergence budget. | +| `architecture_review_required` | The lane needs architecture direction before more repair. | +| `review_policy_blocked` | Review cannot proceed from available evidence. | +| `dependency_blocked` | The node is waiting on dependency state that is not progressing. | +| `research_contract_required` | Execution uncovered a missing or contradictory decision contract. | +| `ownership_ambiguous` | Tracker, PR, branch, or runtime ownership evidence is contradictory. | + +These outcomes should route to failure attribution, research-contract feedback, +architecture review, or manual attention. They must not spin in automatic retries. + +## Harness Improvement Loop + +Loop outcomes are training signals for the Decodex harness. Runtime telemetry, +private execution evidence, review-stop reasons, validation failures, no-effective-diff +attempts, dependency blockers, and accepted contract gaps should feed improvements to: + +- prompts and developer instructions +- Decodex skills and plugin guidance +- validators and repo gates +- issue templates and briefing quality +- ready-node selection and conflict-domain policy +- future loop guardrails + +Harness improvement does not retroactively change a lane's accepted Decision Contract. +It also does not authorize automatic execution from latent research output. Apply +future policy changes only after the relevant spec, decision, or project contract is +updated. + +## Non-Goals + +- Do not add a user-visible DAG command surface for ordinary Decodex use. +- Do not turn research into automatic execution without an accepted promotion + boundary. +- Do not expose Codex goal internals as an operator workflow. +- Do not replace normal Linear issues as executable Decodex lanes. +- Do not use lane steer as hidden task replacement. +- Do not implement plugin UX in this spec; plugin and UI work must follow downstream + implementation issues. diff --git a/docs/spec/review-orchestration.md b/docs/spec/review-orchestration.md index 8e18eebae..1ec0e40cb 100644 --- a/docs/spec/review-orchestration.md +++ b/docs/spec/review-orchestration.md @@ -13,6 +13,9 @@ This document defines the target orchestration contract for review behavior. The ## Relationship to other specs - [`runtime.md`](./runtime.md) defines the runtime success and failure writeback boundary through PR-backed `In Review` handoff. +- [`loop-runtime.md`](./loop-runtime.md) defines the higher-level loop contract for + phase-scoped goals, independent fresh-context review, uncovered direction stops, and + loop guardrails. - [`post-review-lifecycle.md`](./post-review-lifecycle.md) defines the post-`In Review` lane phases and downstream ownership after review handoff succeeds. - [`tracker-tools.md`](./tracker-tools.md) defines the issue-scoped tracker tool surface that records bounded review results and completion signals. - The registered project `WORKFLOW.md` defines the repo-native bounded review method that each review pass must use when evaluating the current lane head. @@ -92,6 +95,10 @@ Rules: - In `"loop"` mode, internal review must use the same bounded review method and normalized review outcomes as any other review pass. - If `"loop"` mode internal review returns an ambiguous or contradictory result that the runtime cannot classify without guessing, stop for `manual_intervention_required`. - Internal review pass transitions into the normal PR-backed review handoff flow, not directly into landing. +- Internal self-review is not the same thing as an independent fresh-context + read-only review. When the loop-runtime risk policy requires independent review, use + the separate review boundary in [`loop-runtime.md`](./loop-runtime.md) before treating + the lane as ready for handoff or landing. ## External GitHub review diff --git a/docs/spec/runtime.md b/docs/spec/runtime.md index b26ef5253..6170e6825 100644 --- a/docs/spec/runtime.md +++ b/docs/spec/runtime.md @@ -13,6 +13,19 @@ Defines: The runtime scope, source-of-truth boundaries, eligibility rules, lane - One direct `codex app-server` session per run attempt. - Supported host targets are Unix only: macOS and Linux. Windows is outside the runtime contract. +## Relationship To Loop Runtime + +[`loop-runtime.md`](./loop-runtime.md) owns the natural-language-first layer above +individual issue lanes: Decodex-native Research/Decision, latent Loop/Decision +Contracts, internal Execution Programs, phase-scoped goals, unattended execution +behavior, and loop guardrails. + +This document owns the lower-level lane runtime. A promoted Execution Program may +shape queue intent and normal Linear issues, but executable work still enters this +runtime as ordinary issue lanes with leases, attempts, validation, review handoff, and +tracker writeback. The internal program graph is not a replacement for Linear workflow +state or this state machine. + ## Upstream alignment - Upstream Symphony is the architectural reference for scheduler and runner ownership. @@ -104,6 +117,12 @@ This boundary does not create a project-local runtime database contract. The run - Lease: A local guarantee that only one active `decodex` run is processing a given issue. - Run attempt: One bounded orchestration pass for one issue. - Lane: The branch plus linked Git worktree checkout associated with one issue. +- Decision Contract: An accepted loop-runtime decision package, also called the + Loop/Decision Contract. Research output is only latent until accepted or promoted + under [`loop-runtime.md`](./loop-runtime.md). +- Execution Program: Internal loop-runtime state derived from accepted Decision + Contracts. It may use DAG semantics, but normal Linear issues remain the executable + lanes. - Terminal tracker state: A state that should not be auto-started by `decodex`. The default set is `Done`, `Canceled`, and `Duplicate`. ## Eligibility