# Wayloop — full documentation
![Wayloop](assets/brand/mark.svg){ width="96" } # Wayloop

Spec-driven agentic loop.

From idea to merged code, in your issues, with humans at the gates.

Wayloop runs a software project with coding agents, from the first idea to the merged pull request. Specifications capture intent, a deterministic loop moves the work forward, the plan lives in your issue tracker, and people decide at the gates. [How the loop works](concepts/the-loop.md){ .md-button .md-button--primary } [Architecture](concepts/architecture.md){ .md-button }
!!! note "Status" Pre-alpha. There is no release yet. The concept pages describe the design and state, on each page, what of it exists today. What comes next is in the [roadmap](project/roadmap.md).
- __The engine decides__ --- A state machine written in Rust chooses every step and verifies it with deterministic checks. A model never declares its own work finished. [Architecture](concepts/architecture.md) - __Your tracker is the database__ --- Plan, progress, decisions and questions live in your issues; specifications live in the repository. Remove Wayloop and the project still reads. [State in the tracker](concepts/state-in-the-tracker.md) - __Humans at the gates__ --- The loop runs unattended between approval states and stops at them, with a question in a fixed format on the issue. [Gates](concepts/gates.md) - __A deterministic ledger__ --- Append-only, hash-chained events. The state is a function of the ledger, and every session hands over a validated summary. [Ledger](concepts/ledger.md) - __Greenfield and brownfield__ --- On an existing codebase, a survey maps the code and writes documentation that cites file and line for every claim. No embeddings. [Brownfield survey](concepts/brownfield-survey.md) - __Tokens are a budget__ --- Every phase has a budget and the ledger measures the cost of each issue, so that the cost of the loop is known, not guessed. [The loop](concepts/the-loop.md)
## For agents This documentation is also published as plain text for agents: [`llms.txt`](https://salvo8519.github.io/wayloop/llms.txt) and [`llms-full.txt`](https://salvo8519.github.io/wayloop/llms-full.txt). # Getting started This section is for installing Wayloop and running it on a first project. Wayloop has no release yet, so there is nothing to install; the work towards the first release is in the [roadmap](../project/roadmap.md). # Guides This section is for guides to tasks done with Wayloop, from a coding agent or from the command line. No guide is published, because no command of the loop is released; the work towards it is in the [roadmap](../project/roadmap.md). # The loop The loop keeps the plan and the work aligned. It decomposes the project, runs the work and, at every event, proposes how the plan should change. It never changes the plan on its own. !!! note "Status" This page describes the design of the loop, recorded in the [architecture decisions](../project/adr/index.md) and the specifications. The core fixes the steps of the issue cycle, which `wayloop steps` prints in order ([reference](../reference/index.md)); the rest of the loop is not built. What comes next is in the [roadmap](../project/roadmap.md). ## Four movements 1. **Decompose.** From an idea, or from the survey of an existing codebase, the engine guides the descent through the levels of the project: milestones, epics, user stories, specifications, tasks and issues. Agents write each level; the engine validates it before the next level starts. 2. **Execute.** Issues move through the issue cycle below. Every step is recorded in the [ledger](ledger.md). 3. **Reconcile.** Every event produces a proposed change to the roadmap: an issue closed, a pull request merged, a new request from the maintainer, work discovered during development, a specification changed, a gap found by the survey. The proposal is a readable difference that a person approves or corrects. 4. **Re-plan.** After approval, the engine recomputes dependencies, next tasks, sprint lanes and the progress of each milestone, and updates the tracker. ## The issue cycle | Step | What happens | Who | | --- | --- | --- | | Claim | The issue is assigned to one session, labelled in progress, given a branch and a worktree | Engine | | Re-analysis | The issue, its story, its specification and the code involved are read again; the specification is checked against the current code | Agent | | Counter-review | A second agent looks for gaps, edge cases and contradictions; each objection ends in a recorded ruling or a question | Agent | | Checklist | The task checklist is generated from the specification and published on the issue | Agent, validated by the engine | | Build | Tests where they pay, then the code | Agent | | Verify | Deterministic checks decide whether the work is done | Engine | | Review | Proportional to risk: none, one pass, or two | Agent | | Pull request | Linked to the issue and to the requirements it implements | Engine | | Merge | Approval state: a person decides | Maintainer | ## One turn of the loop The engine owns the state machine; agents are workers called for one step at a time. 1. Read the state: tracker, repository and ledger. 2. Choose the next transition allowed by the state, with its dependencies satisfied. 3. Prepare a minimal brief: only the files and excerpts that the step needs, within the token budget of the phase. 4. Call an agent: Claude Code, Codex or another configured executor. 5. Verify with deterministic checks and record the outcome, the cost and the rulings. A model never declares its own work finished: a check does. ## Where the loop stops - **Approval states**: the council report, the roadmap, an approved specification, a merge. - **Limits**: a maximum number of turns per issue and a token budget per phase and per sprint. - **Repeated failure**: when the same check fails a configured number of times, the loop opens a question instead of trying again. See [Gates](gates.md). # State in the tracker Wayloop has no state of its own. The plan, the progress, the decisions and the questions live in the issue tracker; specifications live in the repository; only session checkpoints stay on the local machine. !!! note "Status" This page describes the design recorded in [ADR 0002](../project/adr/0002-tracker-as-database.md). The engine has no tracker adapter today. This repository applies the design by hand: the plan is `roadmap/roadmap.yaml`, and `scripts/roadmap.py sync` copies the state of every issue from GitHub into it. What comes next is in the [roadmap](../project/roadmap.md). | What | Where it lives | Why | | --- | --- | --- | | Roadmap, epics, stories, tasks | Issues, sub-issues, dependencies, issue types, milestones | Visible to the team and to any tool; it survives the removal of Wayloop | | Progress, questions, decisions, gate outcomes | Fields and comments of the issues | Gates become asynchronous: a decision can be taken from a phone | | Living specifications and change deltas | The repository, linked from the issue | They change with the code and are reviewed in pull requests | | Session checkpoints | The local machine, never committed | Only to resume interrupted work | | Tracker cache | The local machine, rebuildable | Speed and determinism; never a source of truth | ## Where the design is under strain, and how it holds - **Speed.** Remote APIs are slow and rate-limited. The engine works on a local cache updated incrementally, which can be deleted and rebuilt at any time. - **Free text.** People edit issue bodies too. The engine uses native fields (sub-issues, "blocked by" dependencies, issue types) and a structured block validated by a schema; anything that does not validate becomes a question, never a silent error. - **History of the plan.** Each proposed change is a comment carrying the difference and a gate label; the approval stays in the issue timeline. - **Concurrency.** An issue is claimed with an assignee and a label, and written only if it has not changed since the last read. - **Trackers without native relations.** On the free tier of GitLab, "blocks" relations and epics are not available; the structured block carries them instead. - **Chains of events.** A merge restarts reconciliation through a workflow. Events produced by the bot only create proposals, are idempotent and are grouped, so the loop never feeds itself. ## The removal test The design is right only if a project stays readable after Wayloop is removed: issues, specifications and hand-over comments must tell the whole story on their own. # Gates A gate is a state that the loop cannot pass on its own. The loop runs unattended between gates; at a gate it stops, asks, and waits for a person. !!! note "Status" This page describes the design of the gates. In the core, `merge` is the approval step of the issue cycle. In this repository the gates are applied by hand: agents ask questions with the label `needs-decision`, and the maintainer approves the roadmap, the specifications and the merges of engine changes. What comes next is in the [roadmap](../project/roadmap.md). ## Approval states | Gate | Decided by | | --- | --- | | Council report | Maintainer | | Roadmap and every proposed change to it | Maintainer | | Specification `Approved` | Maintainer or the owner of the area | | Merge | Maintainer, or automatically for the smallest risk tier when the maintainer allows it | ## Questions When an agent needs a decision, the issue receives the label `needs-decision` and a question in a fixed format: 1. **Context**, in three lines at most. 2. **Options**, each with its cost. 3. **Recommendation** of the agent, with its reason. The answer is a comment or the choice of an option. The loop resumes from there. Questions do not get lost in a closed chat session: they stay on the issue, next to the work they concern. ## When an agent does not stop Between gates an agent decides and records a ruling in the ledger: what it decided, why, and what it costs if the decision is wrong. It stops only for an irreversible or destructive operation, a security-sensitive action, a side effect outside its worktree, a plan so broken that every path is a guess, or a methodology choice that belongs to the maintainer. # Ledger The ledger is an append-only log of events, written only by the engine and never by a model. The state of the loop is a function of the ledger: replaying the events from the start always gives the same state. !!! note "Status" This page describes the design of the ledger, recorded in [ADR 0003](../project/adr/0003-deterministic-ledger.md). No code writes or reads a ledger today. What comes next is in the [roadmap](../project/roadmap.md). | Element | Format | Rule | | --- | --- | --- | | Event | JSON Lines, one event per line | Fixed fields: sequence, UTC instant, actor, issue, step, outcome, tokens, hash of the input, hash of the previous event | | Current state | YAML | A projection rebuilt from the ledger, never edited by hand | | Session summary | JSON validated by a schema | Done, rulings, open questions, next steps, files touched, cost; published on the issue as the hand-over comment | | Snapshot | JSON | The full state at a point of the ledger, so that months of events are not replayed | ## Why it is deterministic - **Models do not write the ledger.** Their output enters only after schema validation; invalid output becomes an error event, never a corrupted state. - **Hash chain.** Every event carries the hash of the previous one: an edit or a gap in the log is visible immediately. - **Replay is a test.** The design requires a CI test that replays the ledger and compares the state with the YAML projection. ## Long life cycles A project can last months and hundreds of sessions. Three mechanisms keep memory bounded. 1. **Hierarchical roll-up.** Session summaries merge into the issue summary when the issue closes; issue summaries merge into the milestone summary. Every level has a maximum size in tokens. 2. **Periodic snapshots.** After a snapshot, earlier events can be archived. 3. **Versioned schemas.** Every event and summary states its schema version; the engine migrates older versions. An agent arriving after weeks reads the milestone summary, the issue summary and the last hand-over comment: a small context of known size, whatever the history of the project. ## Finding things The files are the source; an SQLite index with full-text search is built from them and can always be rebuilt. Agents query it through the engine, never directly. See [ADR 0007](../project/adr/0007-files-as-source-sqlite-as-index.md). ## Two memories, stated plainly The local ledger is the operational log of a machine and is lost with it. The durable memory of the project is the set of summaries published on the issues. # Brownfield survey On an existing codebase the loop starts with one more step, the survey. The engine maps the code deterministically; agents write documentation backed by evidence; the result becomes the indexed context of every later step. !!! note "Status" This page describes the design of the survey. No part of it is built today. What comes next is in the [roadmap](../project/roadmap.md). | Step | Done by | Output | | --- | --- | --- | | Scan | Engine | Module tree, languages, entry points, dependencies, token count per file | | Map | Engine | Symbols extracted with tree-sitter, import and call graph, ranking of central files, a map within a token budget | | Documentation with evidence | Agents, on top of the map | Architecture, conventions, domain glossary, main flows; every claim cites file and line, and whatever cannot be shown goes into a section of unverified items | | Surveyed specifications | Agents | Living specifications rebuilt from the current behaviour, in state `Surveyed` until the maintainer approves them | | Gaps | Agents | A document of gaps only (missing tests, undocumented parts, risks), without documenting again what already exists | | Index | Engine | A lexical and structural index, updated incrementally, queried through the engine | ## Evidence, not plausibility Answers distinguish observations, limits and unknowns, and "not found" is a valid answer. This is what keeps an agent from inventing an architecture. ## No embeddings The index is lexical (BM25) and structural (tree-sitter symbols): fast, deterministic and repeatable. Embeddings would add a model, a store to maintain and results that are not repeatable, to help only with natural-language questions. Teams that want semantic search use an external tool next to Wayloop. See [ADR 0004](../project/adr/0004-no-embeddings.md). ## Saving tokens - A map within a budget instead of whole files. - Filtered reads of specifications: only the requirements that matter to the step. - Compact JSON output from every command. - For shell output, integration with an existing output compressor rather than a rewrite. # Architecture One engine decides; thin adapters translate. The engine never calls a model, and agents never write the state by hand. The rule is recorded in [ADR 0001](../project/adr/0001-rust-engine-thin-adapters.md). ## What exists | Component | Path | What it does today | | --- | --- | --- | | Schemas | `crates/wayloop-schemas` | Rust library with no I/O, home of the contract types that mirror the JSON schemas: the error report ([below](#errors-are-values)), the envelope with its exit codes ([below](#the-envelope)), the brief and the input and data of `validate`, with one type per value form (identifiers, project paths, language tags, numbers from 1). Each derives its JSON Schema inside the subset of the core ([below](#schemas-derived-from-the-contract-types)). | | Core | `crates/wayloop-core` | Rust library with no I/O. It fixes the vocabulary of the issue cycle: the nine steps in order, their stable identifiers, and which step is an approval state. It re-exports the error of every refusal and the envelope, and computes the hash of an input from its canonical JSON ([below](#the-envelope)). It reads the JSON schemas of the contracts with its own interpreter ([below](#the-schema-interpreter)). Its entry point runs the command `validate`, which checks briefs against their schema ([reference](../reference/validate.md)). | | Runtime | `crates/wayloop-runtime` | Rust library that runs the work the core decides ([below](#synchronous-core-asynchronous-runtime)). It holds no code yet. | | Command line | `crates/wayloop-cli` | The `wayloop` binary, an adapter only: it parses arguments, calls the core and prints JSON. Commands: `version` and `steps` ([reference](../reference/index.md)), and `validate`, which prints the envelope of the entry point ([reference](../reference/validate.md)). | | Schema generator | `crates/wayloop-schemagen` | A tool of the repository, not published: it prints the snapshots of the contracts, which `uv run just generate` writes under `schemas/` ([below](#snapshots-of-the-contracts)). | | Agent content | `.agents/` | Roles and skills in the open Agent Skills format, with generated mirrors for Claude Code. They are used to build Wayloop itself. | | Process | `roadmap/`, `specs/`, `sprints/`, `scripts/` | The plan as code, synchronised with the GitHub issues; specifications with numbered requirements; sprint lanes of disjoint paths; the checks run by CI. | Wayloop has no release yet. The components of the engine, and the order in which they are built, are in the [roadmap](../project/roadmap.md). ## Crate layout The engine is a Cargo workspace of four crates. Each one has a single role, and dependencies point in one direction only: towards the pure crates. A fifth crate of the workspace, `wayloop-schemagen`, is a tool at the level of the adapters, never published. ```text wayloop-cli adapter: translates a channel, decides nothing | v wayloop-runtime I/O, no decisions | v wayloop-core decisions, no I/O | v wayloop-schemas contract types, no I/O ``` | Crate | Role | May depend on | Performs I/O | | --- | --- | --- | --- | | `wayloop-schemas` | Contract types of the JSON schemas under `schemas/` | no Wayloop crate | No | | `wayloop-core` | All decision logic: artifact model, state machine, ledger rules | `wayloop-schemas` | No | | `wayloop-runtime` | Queue, parallel workers, tracker calls, single writer to the ledger | `wayloop-core`, `wayloop-schemas` | Yes | | `wayloop-cli` and the other adapters | Translation between a channel and the engine | any of the above | Yes | | `wayloop-schemagen` | Prints the snapshots of the contracts; not published | `wayloop-core`, `wayloop-schemas` | Yes, standard output only | - **One entry point.** The core exposes one function to every channel: command, canonical input and context in, envelope out ([ADR 0028](../project/adr/0028-one-contract-on-every-channel.md)). It is `wayloop_core::run`, at the root of `wayloop-core`; adapters call it and only translate its input and its envelope, `Envelope`, whose data is the data type of the command written as JSON in one place. `wayloop_core::run_json` takes the input as JSON text: text that is not JSON, holds a number beyond a double or repeats a key in one object is refused with the reason `syntax`, `range` or `duplicate` before the command runs. The context carries the settings of the channel: the dry run, written in `meta.dry_run`, and the requested version of the command; without one the current version runs and is listed in `meta.defaults_applied`, and a version the engine does not run is refused (ADR 0028, amended on 2026-11-20). `wayloop_core::usage_error` and `wayloop_core::input_unreadable` build the envelopes of a channel that was not used as documented and of an input it could not read, so that the command line prints an envelope for every outcome. - **Allowlisted dependencies.** Each pure crate may depend only on the crates of its reviewed allowlist. Both may use `serde` with its derive macros and `serde_json`, which perform no I/O, with the crates they reach (`serde_core`, `serde_derive`, `proc-macro2`, `quote`, `syn`, `unicode-ident`, `itoa`, `zmij`, `memchr`), and `schemars`, which derives the JSON Schema of the contract types and performs no I/O, without its `preserve_order` feature, with the crates it reaches (`schemars_derive`, `serde_derive_internals`, `dyn-clone`, `ref-cast`, `ref-cast-impl`) ([ADR 0030](../project/adr/0030-contracts-generated-from-rust-types.md)); `wayloop-core` may also use `wayloop-schemas`, and `wayloop-schemas` no Wayloop crate. `scripts/check_core_io.py` resolves each pure crate on its own with `cargo tree` (normal dependencies, every target, all its features, the lock file left unchanged) and fails on every crate reached outside the allowlist, printing the path that reaches it and naming known I/O crates. The allowlists also enforce the direction of the table above: a pure crate never depends on the runtime or an adapter, and the schemas never depend on the core. A feature that another crate of the workspace enables on a shared dependency is not blamed on a pure crate. Development dependencies (tests only) and build dependencies (run at build time) are not part of the shipped crate and are skipped. Extending an allowlist is a reviewed change to the script. - **No I/O in the source.** The compiler refuses it. The `clippy.toml` of the workspace, the only one, lists the parts of the standard library that perform I/O or read ambient state: files (`std::fs`), the network (`std::net`), processes (`std::process`), the environment (`std::env`), the standard streams, threads, clock reads (`SystemTime::now`, `Instant::now`) and hash maps seeded at random (`HashMap`, `HashSet`; `BTreeMap` and `BTreeSet` are used instead). The Clippy lints `disallowed_methods` and `disallowed_types` apply the lists to every crate and every target by default, tests included. A crate that performs I/O, the runtime, an adapter or the schema generator, opts out explicitly with an `allow` of the two lints at the root of each of its targets that needs it. Each pure crate also forbids at its root `print_stdout`, `print_stderr`, `dbg_macro`, `disallowed_methods` and `disallowed_types`: `forbid`, unlike `deny`, cannot be lifted by an `allow` further in. The lints follow name resolution, so an alias or a nested import does not escape them. `cargo clippy` applies them in `just check` and in CI. `scripts/check_core_io.py` fails when the attribute or an entry of the `clippy.toml` is removed, when a crate has a `clippy.toml` of its own, which Clippy would read instead of the workspace one, and when a manifest allows the two lints. - **No panic.** Every crate of the workspace refuses the Clippy lints that let code panic or stop the process: `unwrap_used`, `expect_used`, `panic`, `todo`, `unimplemented`, `unreachable`, `indexing_slicing`, `string_slice`, `get_unwrap`, `panic_in_result_fn`, `exit` and `mem_forget`, on top of the `all` and `pedantic` groups. They are set in the workspace manifest and fail `cargo clippy -D warnings` in `just check` and in CI. Tests may unwrap, expect, panic and index: the `clippy.toml` of the workspace allows it in test code only. A failure is an error value; the command line turns it into an exit code, even when it cannot write its output. ## Synchronous core, asynchronous runtime The split between the core and the runtime around it is the subject of [ADR 0006](../project/adr/0006-synchronous-core-asynchronous-runtime.md). The core is synchronous and pure: given a state and an event, it returns the next state and the work to do. All concurrency lives in the runtime. - **Queue.** Ready work is derived from the state (dependencies satisfied, lane free), not kept in an external broker. There is nothing to install and nothing to lose. - **Parallel workers.** Issues of different lanes run in parallel, each in its own git worktree. Lanes declare disjoint paths, checked before the sprint starts, so parallel agents never edit the same files. A configurable limit caps the number of agents running at once. - **Single writer.** Workers send their results to one writer that validates them and appends them to the ledger in order. Parallel execution never makes the state non-deterministic. - **Batches.** Tracker calls are grouped to respect rate limits. Independent, non-interactive steps (council opinions, documentation of a module, reviews) can go through the batch APIs of model providers where they exist, which are cheaper and slower. This repository already works this way by hand: sprint lanes declare disjoint paths, checked by `scripts/sprint.py`, and every issue is worked in its own git worktree. ## Contracts Every input and output crossing the engine boundary is JSON with a versioned schema. An adapter that needs a new behaviour asks the engine for it; it never implements it. The envelope shared by every command, with its error codes and exit codes, is the subject of [ADR 0009](../project/adr/0009-contract-guidelines.md). ### Errors are values The engine never panics on bad input: it returns `wayloop_core::Error`. The type is a contract type: it is defined in `wayloop-schemas` and re-exported by the core. It carries as data every field of a refusal that an agent acts on (ADR 0009, C3), and where the faulty value is stored: | Field | Meaning | | --- | --- | | `code` | Stable identifier of the refusal; a new meaning gets a new code, never a renamed one (C8) | | `message` | What went wrong, for a person | | `pointer` | RFC 6901 pointer from the root of the input sent; empty for the whole input; a value of the type `Pointer`, checked when it is parsed from text, or built one escaped token at a time (`join`, `join_index`) | | `pointers` | Pointers to the other parts of the input involved, such as both sides of a conflict; optional | | `reason` | One value of the documented enum: `syntax`, `missing`, `unknown_field`, `duplicate`, `type`, `enum`, `conflict`, `requires`, `range`, `length`, `state`, `stale`, and `internal` for a failure of the engine itself, which is not a refusal of the input | | `expected` | The values accepted at `pointer`, never a pattern; optional, and `[]` when no value is accepted | | `fix` | The closest field for a misspelt key, or a corrected value; optional | | `source` | Where the value is stored: `{file, line}` for a repository file, with `line` only when it is known, `{issue}` for a tracker issue, `{milestone}` for a tracker milestone, with lines and numbers from 1; absent for a document sent directly | | `document` | Index, from 0, of the document of the input the error belongs to, whose `pointer` is then relative to that document; absent for an error of the input itself | An optional field that is not given is left out of the JSON form; a list given empty is written `[]`, because absent means not given and `[]` means none (ADR 0009, C2). The error report, `wayloop_core::ErrorReport`, lists every error found in one pass in `errors`, in the order found, and repeats the first one at the top level, so `errors[0]` always equals the top level. `Error` and `ErrorReport` implement `Display` and `std::error::Error`. A code is a constant of the type `Code`, so that one place lists every code of the engine; the codes themselves come with the specification of each command. ### The envelope Every command returns one envelope (ADR 0009, C1), a contract type of `wayloop-schemas` re-exported as `wayloop_core::Envelope`, generic over `D`, the data type of the command; the diagnostics, the meta and the error report inside it are defined once for every command ([ADR 0030](../project/adr/0030-contracts-generated-from-rust-types.md), G1): | Field | Meaning | | --- | --- | | `command` | Identifier of the command | | `data` | The result; present only when the command succeeded | | `error` | The error report ([above](#errors-are-values)); present only when the command was refused or failed, and then `data` is absent | | `diagnostics` | `warnings` in the shape of an error; `not_done`, one `{check, reason}` for each check not run, with the reason `not_built` (the part of the engine that runs it is not built yet) or `input_absent` (the input it needs was not given); `checks`, the checks run. Each list is always written, `[]` when empty | | `meta` | `engine_version`, `envelope_version` (1), `command_version`, `input_hash`, `dry_run` and `defaults_applied`: one `{pointer, value, reason, message}` for each default the engine applied, where `reason` is an identifier and `message`, for people, is optional | Every identifier in the envelope (a check, a reason, an error code) is a stable `snake_case` value, documented with the command that writes it; clients accept values they do not know (ADR 0009, C5). `Envelope::exit_code()` gives the exit code of ADR 0009 C7: 0 for a result with `data`, 1 for a refused input, 2 for a channel not used as documented (code `usage`), 3 for an input that could not be read (code `input_unreadable`), 5 for an internal error of the engine; it returns `Outcome::exit_code()`, the one place where an outcome is mapped to an exit code. An internal error is written in `error` as a refusal is; its errors have the reason `internal`, which tells the two apart in the JSON. The envelope holds nothing that depends on the machine or the moment: no clock time, host name or absolute path. An outcome is built only through constructors that refuse, by returning `None`, what the contract does not define: `Outcome::success` refuses data written as null (null means not given, ADR 0009 C2) or with no JSON form, `Outcome::refused` a report with an error of reason `internal`, `Outcome::failed` a report with an error of any other reason, `Outcome::unusable` and `Outcome::environment` a report whose errors are not all of the codes `usage` and `input_unreadable`. `Outcome::internal` always builds a failure, for a caller that must give an outcome when no other can be built. Every envelope the engine can build is therefore one its reader accepts. The reader refuses the same cases, and a document with both `data` and `error`, or with neither. The schema requires `error` when `data` is absent; the subset of the interpreter has no negation, so only the type refuses both. The schema of the envelope of any data is that of `Envelope`, committed as the snapshots of the contract `envelope/result`; the output schema of a command is the envelope with the data type of that command. The tests of the core load every snapshot with the interpreter and the oracle. `meta.input_hash` is the SHA-256 of the input serialised as canonical JSON (RFC 8785), in lower-case hexadecimal, so the same input gives the same hash on every channel and platform: - **Canonical JSON** (`wayloop_core::canonical`). Object members are sorted by the UTF-16 code units of their keys, never by the order of the map; strings are escaped as ECMAScript `JSON.stringify` escapes them; numbers are written as the IEEE 754 double they denote, in the ECMAScript form, so `4.50` is written `4.5` and `1E30` is written `1e+30`. An integer beyond 2^53 in magnitude is written as the nearest double, as RFC 8785 requires, so two such integers can share a hash. `4364.0` and `4364` denote the same double, so they hash the same. NaN and the infinities cannot be held in a JSON value, so the function is total. The writer keeps its own stack, so a deeply nested input cannot exhaust the call stack. It is checked against the examples and the number samples of RFC 8785. A JSON value cannot hold duplicate keys, which RFC 8785 refuses: `serde_json` keeps the last of two equal keys, so whoever parses JSON text must refuse them first, with the reason `duplicate`. - **Number parsing.** The workspace declares `serde_json` once, with the `float_roundtrip` feature, which adds no crate: every number is read as the nearest double, as other JSON parsers read it. The default parser of `serde_json` can be one unit in the last place off, and the same input would then hash differently on two channels. Tests of the core fail if `float_roundtrip` is dropped or if `arbitrary_precision`, which keeps the text of a number instead of its double, is enabled by any crate. - **SHA-256** (`wayloop_core::sha256`). Written by hand from FIPS 180-4, so that the core needs no hashing crate (SPEC-0001 plan, D3). It is checked against the published test vectors and, on random inputs, against a hashing crate used in tests only (`sha2`, a development dependency, which is never shipped and is not on the allowlist of the core). The hash identifies content and protects no secret, so it makes no attempt at constant time. ### The schema interpreter The schemas of the contracts are JSON Schema (draft 2020-12), derived from the contract types (see the next section). The core reads them with a small interpreter of a documented subset, `wayloop_core::schema`, so that every error of a document is reported in one pass with its pointer and its reason, and the core needs no validator crate (plan of SPEC-0001, D5). A schema that uses a keyword outside the subset, or a keyword out of its place, is refused when it is loaded: no rule of a schema is silently ignored. | Keyword | Meaning | Reason of the error | | --- | --- | --- | | `type` | `boolean`, `integer`, `string`, `array` or `object`; an integer is a finite number without a fraction, so `2.0` is one | `type`, and nothing else is checked on that value | | `enum`, `const` | Accepted values: strings, integers, booleans or `null`, compared by value | `enum`, with the accepted values in `expected` | | `minLength`, `maxLength` | Bounds of a string, in Unicode code points | `length` | | `minItems`, `maxItems` | Bounds of an array | `length` | | `minimum`, `maximum` | Inclusive integer bounds, beside `type: integer` | `range` | | `format` | A named format of the core, on strings | `syntax`, with a corrected value in `fix` when one can be derived | | `items` | Schema of every element of an array | | | `properties` | Schema of each declared member; with `additionalProperties: false` any other member is refused, without it the object is open and other members are accepted unchecked, as in output schemas (ADR 0009 C5, amended on 2026-11-20) | `unknown_field`, with the closest declared key in `fix` | | `required` | Declared members that must be present | `missing` | | `if` and `then`, `allOf` | Conditional requirements: when the value matches the condition of `if`, the members of the `required` of `then` must be present; `allOf` lists such pairs | `requires`, with the members the condition tested in `pointers` | | `$ref`, `$defs` | A reference to a definition of the same file, whose name has no `/`, `~` or `%` | | | `$schema`, `$id`, `$comment`, `title`, `description` | Annotations, at the root for `$schema` and `$id` | | The condition of an `if` uses `properties`, `required`, `enum`, `const` and `contains`. There is no `pattern`: the core holds no regular expression engine, and a named format gives a precise `fix`. The named formats are `date`, `utc-date-time` (with the suffix `Z`), `language-tag` (language, script, region and variants of BCP 47), `tracker-handle`, `project-path` (a path relative to the root of the project in one spelling: segments joined by `/`, none empty, `.` or `..`; no `\` and no drive letter), the identifiers of each artifact type (`brief-id`, `council-id`, `gate-id`, `epic-id`, `story-id`, `spec-id`, `change-id`, `task-id`, `milestone-id`, `handover-id`) and the identifiers of parts (`requirement-id`, `criterion-id`, `decision-id`, `question-id`), with the canonical forms of SPEC-0001. The documentation of the module lists each form and each fix. The list of named formats is one enum, `wayloop_schemas::Format`, and the format checker of the core matches on it exhaustively: a format added to the enum does not compile until the core checks it. - **Null.** A member of an object set to `null` is not given, exactly as an absent member (ADR 0009 C2): accepted when optional, `missing` when required, never an unknown field, and absent for a condition. A `null` element of an array is a value like any other and fails `type`, since no type of the subset is `null`. - **Order of the errors.** Errors come in document order: the errors of a value before the errors inside it, the members of an object in the byte order of their keys, the elements of an array by index, and the absent members of an object after its present ones. A member missing under both `required` and a `then` is reported once, as `missing`. - **Closest key.** The fix of an unknown key is a declared key not already present, at an optimal string alignment distance (the restricted Damerau-Levenshtein distance) of at most a third of the length of the unknown key; ties go to the first key in byte order. A key longer than 64 characters gets no fix. - **Integers.** Every integer the interpreter checks lies within plus or minus (2^53 - 1), the range in which an IEEE 754 double holds every integer exactly (RFC 7493, I-JSON); a value beyond is refused with the reason `range`, whatever its schema says. Integers in a schema are held to the same bound. Numbers are compared by value, so `4364.0` equals `4364`. A number in a part of a document that no schema describes is not checked. Numbers are read as IEEE 754 doubles, as RFC 8785 reads them, so digits beyond that precision are not seen: `1.0000000000000001` is the integer 1. - **Bounds.** A schema is at most 32 levels of subschemas deep, counted through references, and a reference that reaches its own definition is refused. The interpreter descends into a document only where its schema does, so its recursion is bounded whatever the document. - **Oracle.** The tests check every schema and document they use with a JSON Schema validator crate, a development dependency that is never shipped; it must agree with the interpreter on the verdict. The named formats are checked in the oracle by regular expressions written from SPEC-0001, independently of the parsers of the core. Two rules of Wayloop are not JSON Schema, so the oracle sees the document without its members set to null, and the integer bound is added to its verdict; the bound is checked on every number, which matches the interpreter only for documents that their schema describes fully, as the documents of the tests are. ### Schemas derived from the contract types Every contract type of `wayloop-schemas` derives its JSON Schema with `schemars`, and its doc comments become the descriptions ([ADR 0030](../project/adr/0030-contracts-generated-from-rust-types.md)). `wayloop_schemas::contract::schema_for` returns the schema of a type for one direction, input or output, and writes no file; `contract::TYPES` lists every contract type whose schema is derived. Every contract type also reads back what it writes: a document its schema accepts deserialises into the type, which writes the same JSON again (`contract::reread`). A closed enum is written with the macro `closed_enum!` of `wayloop_schemas::ident`, one spelling per value read by `id()`, `from_id()` and `Display`; two values with the same spelling do not compile. A closed enum of a contract (`Reason`, `NotDoneReason`) is written with `contract_enum!`, so that its serialised form and the values of its schema read the same spelling; `Format`, whose value `contract::rules::formatted` writes through `id()`, and `IssueStep`, in no contract yet, use `closed_enum!`; `ExitCode`, a number by contract (ADR 0009 C7), has no spelling. A static identifier (`Code`, `Check`, `DefaultReason`) is written with `static_id!`: constants of the engine borrow their text, a value read from a document owns it. What the derive does not write is written once, in the module `contract`: | Need | How it is written | | --- | --- | | A conditional requirement | A function of the type, named in `#[schemars(transform = ...)]`, calls `contract::rules::require_if_present`, `require_if_absent` or `require_if_equals`, which append an `if` and `then` pair to `allOf`; `require_if_absent` tests the member against `const: null`, which holds when it is absent or null, in the interpreter and in draft 2020-12 alike | | A named format | A value form implements `JsonSchema` by hand with `contract::rules::formatted`, from a value of `Format` | | Absent, not null | An optional member, out of `required`, loses the `null` type the derive adds to an `Option` | | An enum value with its meaning | A `oneOf` of documented constants becomes an `enum`, and each value is appended to the description as a line ``- `value`: meaning`` | | Any JSON value | The boolean schema `true` becomes an object schema with a description | | Integer formats | A `format` such as `uint32` is removed; the type and the bounds remain | | Closed inputs, open outputs | In an input every object that declares its members and has no `additionalProperties` gets `additionalProperties: false`; an object that declares none is a free object, written by hand for a document of another schema, and stays open; an output has none | The lines of a doc comment are joined into paragraphs, since they wrap at the width of the code. The generator then checks the rules of the contracts that are not rules of the subset: a description on the root, every definition and every member (one of blanks only is none), the meaning of every enum value in its description, no `additionalProperties` in an output, and at most four levels of objects (ADR 0009 C4). The subset itself has one definition, the loader of the interpreter (ADR 0030 G3): `wayloop_core::schema::contract_schema` runs the checks of the generator and then `Schema::load` on a registered type, and fails with `ContractFault::Rule` or `ContractFault::Subset`. A `null` type, the keywords `pattern`, `default` and `uniqueItems`, a format that is not named, a boolean schema or a map in an input are refused there, at their place. A type whose serialised form the derive cannot describe in the subset has a private form type for its schema and for reading: `Source`, whose forms are one object with optional members and `file` and `line` given together, which the type reads as exactly one form, and `ErrorReport`, the members of its first error merged with `errors`, read only when `errors` starts with those members, and `Envelope`, with `data` and `error` both optional in its schema, read as exactly one of them. A generic type has no schema until its parameter is given, so `contract::TYPES` registers the envelope as `Envelope`, under the name of its schema, `Envelope`. `contract::snapshot` writes the text of a snapshot: the schema with its `$id`, keys in byte order, two-space indentation and a final newline; it writes no file. The tests of the core run `contract_schema` on every type of `contract::TYPES` in both directions, check each schema against the meta-schema of draft 2020-12 with the oracle, and check that the serialised values of the types are accepted and read back into the same JSON. ### Snapshots of the contracts The schemas of the contracts are committed under `schemas/` as snapshots, generated from the types ([ADR 0030](../project/adr/0030-contracts-generated-from-rust-types.md), G5 and G6). One registry, `wayloop_schemas::contract::CONTRACTS`, lists every contract with its area (`artifacts`, `inputs`, `commands`, `envelope`), its name, its current version and the type and direction of each of its files; today it lists the envelope, `envelope/result`, at the version of `meta.envelope_version`. The binary `wayloop-schemagen` runs `contract_schema` on every file of every current version, writes its text with `contract::snapshot` and prints them all as one JSON document; it writes no file. `scripts/schema_snapshots.py` writes those bytes unchanged at `schemas///v.json` (`v.output.json` for the output of a command, `v.input.json` for the input of a hand-over), with the history of each contract in `schemas///index.json`. A version earlier than the current one never changes, and the current version, once released, changes only additively (ADR 0009 C5): the rules are in the [conventions](../project/conventions.md#contract-snapshots). An earlier version is reproduced from its committed file, not from the types, which describe only the current one. `wayloop-schemas` embeds the text of every snapshot of every version, `contract::EMBEDDED`. Since `cargo package` packs only the folder of a crate, the snapshots are embedded from byte-for-byte copies inside it, in `crates/wayloop-schemas/snapshots/`, listed in the generated file `src/contract/embedded.rs`; the check fails when a copy differs from its source. The tests of `wayloop-schemas` check that the embedded current versions are the snapshots of the types, and the tests of the core load every embedded snapshot with the interpreter and the oracle. # Reference This section is for the reference of the commands, the JSON contracts and the error codes of Wayloop. There is no release yet; what comes next is in the [roadmap](../project/roadmap.md). ## Commands of a build from source The `wayloop` binary built from `crates/wayloop-cli` answers the commands below. Each prints one line of JSON on standard output. `version` and `steps` exit with code 0; the version is the one of the workspace manifest. `validate` checks artifacts against their schemas and is described on its own page, [wayloop validate](validate.md). | Command | Output | | --- | --- | | `wayloop version` (also `wayloop --version`) | The name and the version of the engine | | `wayloop steps` | The identifiers of the steps of the issue cycle, in order | | `wayloop validate --input ` | The envelope of the validation of a set of artifacts ([wayloop validate](validate.md)) | ```console $ cargo run -q -p wayloop-cli -- version {"name":"wayloop","version":"0.0.0"} $ cargo run -q -p wayloop-cli -- steps {"issue_steps":["claim","reanalysis","counter_review","checklist","build","verify","review","pull_request","merge"]} ``` Any other command, or no command, prints on standard output the envelope of a usage error (code `usage`, described in [wayloop validate](validate.md#errors)), prints a usage line on standard error, and exits with code 2: ```console $ cargo run -q -p wayloop-cli 2>&1 >/dev/null wayloop: No command was given. Commands: version, steps, validate --input [--command-version ]. ``` When standard output cannot be written, for example because the reading end of a pipe is closed, the command prints the cause on standard error and exits with code 3, an environment error. The exit codes follow [ADR 0009](../project/adr/0009-contract-guidelines.md) (C7). The step identifiers are `snake_case` values of the contract, as every enum value of the JSON contracts ([ADR 0009](../project/adr/0009-contract-guidelines.md), C4), and have the same spelling in every channel. Other spellings, such as the labels of the issue tracker, are produced by the adapters from these values. Adding a step is an additive change; renaming or removing a step is a breaking change of the contract. The steps themselves are described in [The loop](../concepts/the-loop.md#the-issue-cycle). ## JSON contracts The schemas of the contracts are published with this site, each at the URL of its `$id`, under `https://salvo8519.github.io/wayloop/schemas/`. The history of every contract, with the files of each version and their SHA-256, is in `schemas/index.json` at the same address, and in `index.json` in the folder of each contract. | Contract | History, with the current version and the file of each version | | --- | --- | | Brief ([wayloop validate](validate.md)) | `schemas/artifacts/brief/index.json` | | Input and result of `wayloop validate` ([wayloop validate](validate.md)) | `schemas/commands/validate/index.json` | | Envelope of every command result ([ADR 0009](../project/adr/0009-contract-guidelines.md), C1) | `schemas/envelope/result/index.json` | A version, once released, changes only additively: a new optional input member, a new output member, a new `enum` value. Any other change is a new version, published beside the earlier one, which never changes. Clients accept members and `enum` values they do not know ([ADR 0009](../project/adr/0009-contract-guidelines.md), C5). # wayloop validate `wayloop validate` checks a set of artifacts (briefs, council reports, tasks and the other types of the artifact model) and inputs (pull requests, commits, hand-overs) against their schemas, in one pass, and reports every error with the pointer of the faulty value and the place where it is stored. It changes nothing. Today only briefs are validated against their schema. A document of any other type, a living specification sent as Markdown, and an input are accepted unchecked, and the checks not run are listed in `diagnostics.not_done`; so are the checks across documents (identifiers, links, parts, statuses, naming). This page describes version 1 of the command, as built from source. Its contract is the pair of schema snapshots `schemas/commands/validate/v1.json` (input) and `schemas/commands/validate/v1.output.json` (output), generated from the types of `wayloop-schemas` (ADR 0030); the schema of a brief is `schemas/artifacts/brief/v1.json`. This page explains them. ## Usage ```console $ wayloop validate --input [--command-version ] $ wayloop validate --input - [--command-version ] ``` `--input` names a file holding the canonical input as JSON, or `-` for standard input. `--command-version` requests a version of the command; without it the current version runs, and `meta.defaults_applied` says so. The command prints one envelope on one line of standard output, exactly as the engine wrote it, and exits with the exit code of the envelope. It prints an envelope also when the command line is not understood and when the input file cannot be read; the message for a person goes to standard error. ## What is checked | Check | What it does | | --- | --- | | `document_kind` | Each document has a `kind` among `brief`, `council_report`, `gate`, `milestone`, `epic`, `story`, `specification`, `change`, `task` and `handover`, or is an input with `input_kind` | | `schema_version` | The `schema_version` of each document is a version its type knows; a document of an earlier version is migrated to the current one after it passes the schema of its own version | | `schema_brief` | Each brief passes the schema of its version (`schemas/artifacts/brief/v1.json`): required members, unknown members, types, accepted values, lengths, formats | | `identifier_format` | The `id` is in the canonical form of its type, for example `BRIEF-0001` | Each schema is one check, `schema_`: in `diagnostics.checks` when it ran, in `diagnostics.not_done` with the reason `not_built` when it is not in this version. A check the engine did not run is never skipped silently: | Check | Not run on | | --- | --- | | `schema_`, for example `schema_task` | A document of a type whose schema is not in this version | | `schema_`, for example `schema_commit` | An input whose schema is not in this version | | `markdown` | A living specification sent as Markdown | | `identifier_duplicate` | The set: two artifacts with one identifier | | `links` | The set: links between artifacts, hierarchy, ADR citations | | `parts` | The set: parts of artifacts and operations of change deltas | | `statuses` | The set: transitions and initial statuses against `base` | | `naming` | The set: titles, branch names, commit headers and pull request links | When the input itself is refused, or the command line is not understood, or the input cannot be read, no check runs: `diagnostics.checks` and `diagnostics.not_done` are then empty. ## Input The canonical input is one JSON object. A member set to `null` is not given, exactly as an absent member. The input schema is closed: a member it does not list is refused. | Member | Type | Required | Meaning | | --- | --- | --- | --- | | `documents` | list of objects | yes | One entry per stored artifact or input; `[]` means none | | `base` | list of `{id, status}` | no | Statuses on the default branch of the artifacts of the set | | `policy` | object `{types, scopes, areas}`, each a list of names of the policy, identifiers of at least one character | no | The subset of the project policy the model reads | | `adrs` | list of integers from 1 | no | Numbers of the ADRs of the project | | `language` | BCP 47 tag, for example `it` or `en-GB` | no | The language of the project. No check of this version reads it, so no default is applied or reported when it is absent; a check that needs it lists the default in `meta.defaults_applied` | An entry of `documents`: | Member | Type | Required | Meaning | | --- | --- | --- | --- | | `format` | `document`, `markdown` or `unreadable` | yes | `document`: a JSON value in the normalised form of its type; `markdown`: the text of a living specification; `unreadable`: a file that did not parse | | `document` | object | with `document` | The document | | `lines` | object | no; with `document` and a `file` origin only | The line, from 1, of each value of the document, keyed by its RFC 6901 pointer into the document | | `text` | string | with `markdown` | The content of the file | | `error` | object `{line, message}` | with `unreadable` | Where the parser stopped, from line 1, and its message | | `input_kind` | `pull_request`, `commit` or `handover_input` | no; with `document` only | The type of an input, which has no `kind` member | | `origin` | object, exactly one of `{file}`, `{issue}`, `{milestone}` | no; `{file}` with `unreadable` | Where the document was read; absent for a document sent directly | `origin` has no member naming its form: the member present tells it, as for `source` in the errors. This departs from the letter of ADR 0009 C4 (a choice is a kind plus fields) on purpose, so that the input and the error report spell a place the same way. `file` is a path relative to the root of the project in one spelling: segments joined by `/`, none of them empty, `.` or `..`; no leading `/`, no `\` and no drive letter, so that it never leaves the project and names a file one way only. The command refuses an entry that gives a member of another format (for example `text` with the format `document`), `lines` or the format `unreadable` without a `file` origin, an `origin` with no member or more than one, a key of `lines` that is not an RFC 6901 pointer, and a line that is not an integer from 1. The JSON text of the input must not repeat a key in one object: JSON parsers keep one of the two values, so the engine refuses the text with the reason `duplicate` instead of choosing. A number beyond the range of a double, such as `1e400`, is refused with the reason `range`. ## Output The envelope of [ADR 0009](../project/adr/0009-contract-guidelines.md), version 1 of `envelope/result`, described in [Architecture](../concepts/architecture.md#the-envelope). When the set is accepted, `data` is: | Member | Meaning | | --- | --- | | `documents` | One summary per entry of the input, in its order: `kind`, `input_kind`, `id`, `status` (after migration) and `origin`, each left out when the document does not give it as a string | The output schema is open (ADR 0009 C5, amended on 2026-11-20): a client ignores members it does not know and accepts enum values it does not know. - `diagnostics.checks` lists the checks run and `diagnostics.not_done` the checks not run. - `meta.command_version` is the version that ran. Without `--command-version`, `meta.defaults_applied` lists `{"pointer": "", "value": 1, "reason": "current_command_version"}`: the pointer is empty because the version is a setting of the context, not a member of the input. When `--command-version` names a version the engine does not run, the refusal has the pointer `""` too, and `meta.command_version` is the current version, whose shape the envelope has; when the input is also text the engine cannot read as JSON, the same report lists the version first, then the error of the text. A usage error reports the current version of the command it names, and 1 when it names no known command. - `meta.input_hash` is the SHA-256 of the canonical JSON (RFC 8785) of the input without its members set to null, so an input with `"base": null` has the hash of the input without `base`. For text the engine refuses to read as JSON (not JSON, a key repeated in one object, a number beyond the range of a double), it is the SHA-256 of the bytes received; two channels that send the same text with other line endings or a byte order mark then get different hashes. When no input was read (usage, unreadable file), it is the SHA-256 of no bytes. ## Errors Every error found is listed in `error.errors`; the first one is repeated at the top level of `error`. The order is fixed: 1. The errors of the input itself (code `command_input`) come first and stop the command: no document is checked. They follow the schema pass of the input schema, then the entries in order for the rules the schema cannot state. 2. Otherwise, the errors of the documents, in the order of the documents; within a document, by stage (kind, version and schema first, then identifier); within a stage, in the order of the schema pass: the members of an object in the byte order of their keys (`/aa` before `/zz`), the elements of an array by index, absent members after present ones. The `pointer` of an error of the input points into the canonical input, for example `/documents/0/format`. The `pointer` of an error of a document points into that document, for example `/problem`; `document` gives the index, from 0, of that document in `documents`, and `source` says where it is stored: | Origin of the document | `source` | | --- | --- | | `{file}` | `{file, line}`: the line given in `lines` for the pointer of the error, or for the nearest value that contains it; `{file}` alone when `lines` gives neither, never a guessed line | | `{issue}` | `{issue}` | | `{milestone}` | `{milestone}` | | absent | absent | | Code | Reasons | Exit code | Meaning | | --- | --- | --- | --- | | `command_input` | `syntax`, `duplicate`, `missing`, `unknown_field`, `type`, `enum`, `length`, `range`, `requires`, `conflict` | 1 | The canonical input is refused: it is not JSON, repeats a key, holds a number beyond a double, or breaks its schema or a rule of the section Input; or `--command-version` requests a version the engine does not run (`enum`, the known versions in `expected`) | | `artifact_schema` | `syntax`, `missing`, `unknown_field`, `type`, `enum`, `length`, `range`, `requires` | 1 | A document breaks the schema of its type; also a document without a `kind`, or with a `kind` outside the list (`enum`, with the types in `expected`), a `schema_version` that is missing, not an integer (reported with every other error against the current version) or beyond plus or minus (2^53 - 1) (`range`), and a file that did not parse (`syntax`, at the pointer of the whole document, with its line in `source`) | | `schema_version_unknown` | `enum` | 1 | The `schema_version` is not a version of the type; `expected` lists the known versions | | `identifier_format` | `syntax` | 1 | The `id` is not in the canonical form of its type; `fix` gives the corrected identifier when one can be derived | | `usage` | `syntax` | 2 | The command line is not understood; `command` is the command named, empty when none | | `input_unreadable` | `missing`, `state` | 3 | The input file does not exist (`missing`) or cannot be read (`state`); the envelope holds no path | | `internal_error` | `internal` | 5 | The engine could not compute the result; the input may be valid | An unknown member gets the closest member of the schema in `fix`, for example `problem` for `problema`. ## Exit codes | Exit code | When | | --- | --- | | 0 | The set is accepted: the envelope has `data` | | 1 | The input or a document is refused: the envelope has `error` | | 2 | The command line is not understood, for example `--input` without a value: the envelope has `error` with the code `usage` | | 3 | The input file cannot be read (the envelope has `error` with the code `input_unreadable`), or standard output cannot be written (no envelope can be printed) | | 5 | The engine failed: the envelope has `error` with the reason `internal` | ## Example A brief that writes its problem under the Italian key `problema`, sent directly: ```json {"documents": [{"format": "document", "document": { "kind": "brief", "schema_version": 1, "id": "BRIEF-0003", "title": "Freelancers record their working time from the terminal", "status": "draft", "origin": "light_requirements", "owner": "@example-owner", "problema": "Freelancers lose billable hours because recording time breaks their flow.", "goals": ["Record a time entry with one command"], "users": ["Freelance developers"], "scope_in": ["Time entries"]}}]} ``` The command exits with code 1. The error report holds two errors of the document at index 0: the unknown key, with its fix, then the missing one: ```json {"code": "artifact_schema", "pointer": "/problema", "reason": "unknown_field", "fix": "problem", "document": 0} {"code": "artifact_schema", "pointer": "/problem", "reason": "missing", "document": 0} ``` # Vision Wayloop exists to make agentic software development dependable at the scale of a whole project, not only of a single task. ## The problem Coding agents produce code quickly. Projects still fail in the work around the code: intent that was never written down, plans that drift from what is built, sessions that the next agent cannot resume, and costs that nobody measures. Spec-driven tools capture intent but stop at the plan file; agentic loops keep an agent working but do not know the plan. ## The thesis 1. **The engine decides, agents write.** A deterministic state machine runs the loop and verifies every step with checks, not with the word of a model. 2. **The tracker is the database.** The plan lives where the team already works. Remove Wayloop and the project still reads. 3. **Humans at the gates.** The loop runs unattended between approval states and stops at them. 4. **Cost is measured.** Every phase has a token budget, and the ledger records the cost of every issue. ## Who it is for - **Analysts and designers**, who write intent and want to see it carried through to the code. - **Maintainers**, who want agents to work while they are away and to find questions, not surprises, when they come back. - **Developers**, who want a process that agents follow without being reminded. ## Three tests of success 1. **Removal.** Without Wayloop, the project is still understandable from the tracker and the repository. 2. **Hand-over.** Any agent resumes the work from an issue and its specification alone. 3. **Cost.** The cost per issue is measured and comparable with other approaches on the same work. ## Out of scope - Writing a coding agent: Wayloop drives existing agents. - Semantic search with embeddings: see ADR 0004. - Hosting: Wayloop is a local-first tool and a set of workflows; there is no server to run. # Brand ## The mark A **loop of work that passes through a gate**, on a navy seal. The white ring is the loop; the amber diamond sitting in its opening is the human gate, where the loop stops for a decision; the teal token is the current step moving along the loop. The mark tells the product in one picture: work moves on its own, and people decide at the gates. The gate is a diamond, not a bar: a bar across the opening of a ring reads as a power symbol. The mark stays legible at 16 pixels, so it is also the favicon. Files live in `docs/_shared/assets/brand/` and are generated by `scripts/brand.py`: | File | Use | | --- | --- | | `mark.svg` | Primary mark, on light and dark backgrounds; favicon | | `mark-inverted.svg` | Mark on navy surfaces where a navy seal would disappear | | `logo-light.svg` / `logo-dark.svg` | Horizontal lockup (mark and wordmark) | | `banner-light.svg` / `banner-dark.svg` | README and announcements | | `social-preview.svg` / `social-preview.png` | Repository social preview (1280 by 640) | Keep clear space around the mark of at least a quarter of its width. Do not recolour, stretch, rotate or add effects. Text in the SVG files is converted to outlines: no font is needed. ## Name and voice - **Name:** Wayloop. The way is the roadmap, travelled stage by stage; the loop is the work that runs until each stage is verified. - **Category:** Spec-driven agentic loop. - **Promise:** From idea to merged code, in your issues, with humans at the gates. - **Voice:** corporate and precise. Short sentences, explicit terms, no superlatives, no exclamation marks, no icons or emoji. ## Palette | Name | Hex | Role | Contrast | | --- | --- | --- | --- | | Ink Navy | `#0B1F3A` | Primary: the seal, headings, dark surfaces | 16.5:1 on white | | Deep Navy | `#12325C` | Interactive states on light surfaces | 12.8:1 on white | | Route Teal | `#0F766E` | Links and accents on light surfaces | 5.5:1 on white | | Loop Teal | `#2DD4BF` | The token in the mark; accent on dark surfaces | 9.7:1 on Night | | Gate Amber | `#F59E0B` | Gates and approval states, on navy only | 7.7:1 on Ink Navy | | Slate | `#475569` | Secondary text | 7.6:1 on white | | Night | `#0A1628` | Dark backgrounds | | | Paper | `#F7F8FA` | Light backgrounds | | Gate Amber is never used for text on white: it reaches 2.1:1 and fails WCAG 2.1 AA. Every text colour above meets AA (4.5:1) on the background it is meant for. ## Typography - **Inter** (700 for the wordmark, 600 headings, 400 body): interface and documents. - **JetBrains Mono** (500): code, identifiers, commands. Both are open source under the SIL Open Font License. ## Badges README badges use the palette: Ink Navy for facts about the product, Deep Navy for the technology, Route Teal for the way of working, Gate Amber for the licence. # Roadmap The plan lives in `roadmap/roadmap.yaml` and in the repository issues: milestones, epics and tasks, each task linked to its issue and, when it has one, to its specification. GitHub holds the state of every issue; `scripts/roadmap.py sync` copies it into the file, and this page is generated from the file at every build of the site. Execution comes first: it is the part with the most proven practice behind it. The expert council is the most visible part but the least proven one, and it is built when the rest of the loop can receive its output. --8<-- ".generated/ROADMAP.md" # Release notes What changes for users in each version of Wayloop, in plain language. The technical history of every change is in the [changelog](https://salvo8519.github.io/wayloop/project/changelog/). On the documentation site, the first section lists the changes not yet released. ## Wayloop Unreleased ### Action required - The `wayloop steps` command now prints the step identifiers in `snake_case`, as every value of the JSON contracts: `counter_review` and `pull_request` replace `counter-review` and `pull-request`. Scripts that read these two values need the new spelling. ([#228](https://github.com/salvo8519/wayloop/issues/228)) ### New - The new command `wayloop validate --input ` checks briefs against their schema and reports every error in one pass: the pointer of the faulty value and the document it belongs to, the reason, the accepted values or the corrected key, and the file and line where the value is stored. A brief written against an unknown schema version is refused with the versions the engine knows. Checks of the other artifact types are listed as not done in the result until they are built. The command always prints a JSON result, also when its command line is wrong or its input file cannot be read. ([#256](https://github.com/salvo8519/wayloop/issues/256)) - The JSON schema of the envelope that wraps every command result is published under `https://salvo8519.github.io/wayloop/schemas/envelope/result/`, with the history of the contract in `index.json` and the SHA-256 of every version, so that an integration can pin the exact contract it was built against. ([#294](https://github.com/salvo8519/wayloop/issues/294)) - The result envelope that every command returns now has a JSON Schema generated from the engine's own types, and the engine can only build results that match it: a success carries `data`, a refused input or an engine failure carries `error`, never both, and an engine failure is told apart from a refusal by the reason `internal` of its errors. ([#295](https://github.com/salvo8519/wayloop/issues/295)) ### Fixed - The `wayloop` command no longer stops with an internal error when its output cannot be written, for example when the reading end of a pipe is closed: it reports the cause and exits with code 3, an environment error. ([#238](https://github.com/salvo8519/wayloop/issues/238)) # Changelog All notable changes to Wayloop. Generated from Conventional Commits; do not edit by hand. ## [Unreleased] ### Added - **agents**: Session skills with checkout, hand-over and journal search (#190) - **agents**: Hooks that protect contracts, brief and ask for hand-overs (#208) - **agents**: Nine process roles of the project template (#209) - **agents**: Delivery skills of the project template (#210) - **agents**: Planning skills of the project template (#211) - **agents**: Review and integration skills of the project template (#212) - **agents**: Documentation and release skills of the project template (#213) - **agents**: Skills for the work this repository repeats (#214) - **schemas**: Complete the error report of ADR 0009 (#278) - **core**: Canonical json, sha-256 and the envelope (#282) - **core**: Interpret the json schema subset of the contracts (#285) - **schemas**: Derive the json schema of the contract types (#301) - **schemas**: Generate the envelope from its generic type (#304) - **schemas**: Generate contract snapshots with a history per contract (#305) - **core**: Validate briefs through generated contracts (#288) ### Fixed - **scripts**: Briefing proposes only issues that can start now (#225) - **scripts**: Roadmap sync tolerates issues created moments ago (#250) - **core**: Issue step identifiers are snake_case contract values (#251) - **ci**: Roadmap sync runs only when a real difference can appear (#281) - **ci**: Waive the docs impact check only when every commit carries it (#290) - **ci**: One definition of branch names and closing keywords (#300) ### Changed - **ci**: One source for every rule and value (#302) - **core**: Remove the last duplicated helpers of the pure crates (#306) ### Documentation - **project**: Brand identity, landing page and README banner - **agents**: Agents merge their pull requests, engine changes ask first (#188) - **adr**: Accept ADR 0009, ADR 0010 and ADR 0024 (#215) - **brand**: Site header follows the brand palette (#216) - **project**: Align README and documentation with the project template (#217) - **adr**: Accept ADR 0006 and ADR 0007 (#218) - **adr**: Accept ADR 0008 with the roles of both identifiers (#219) - **adr**: Plan one contract on every channel (#223) - **agents**: Fix defects when found or file them at once (#227) - **specs**: Approve the artifact model (#230) - **adr**: Accept ADR 0028 (#232) - **adr**: Merge waived by policy and staleness scoped to the issue (#234) - **roadmap**: Plan execution modes, loop continuation and batches (#247) - **specs**: Decisions, issues and prerequisites of the artifact plan (#277) - **adr**: Record contracts generated from rust types (#292) - **roadmap**: Plan the typed map of lines (#308) - **roadmap**: Contracts generated from one source are done (#311) - **specs**: Requirement coverage and verification by risk tier (#310) ### Build and CI - **docs**: Cap the Pages deploy timeout at the allowed maximum (#14) - **project**: Issue forms for task, bug and specification request (#148) - **ci**: Keep the required status checks in step with the workflows (#151) - **ci**: Lint workflows, pin actions and scan dependencies (#152) - **deps**: Weekly maintenance and the dependency policy (#153) - **docs**: Keep the documentation in sync with a deterministic check (#154) - **agents**: Automated review of pull requests and documentation (#156) - **roadmap**: Traceability rules of the project template, checked (#170) - **agents**: Generate the Claude Code mirrors from .agents and check them (#189) - **agents**: Standard for skills, agents and hooks, checked in CI (#207) - **core**: Crate layout with pure crates held to allowlists and lints (#237) - **core**: Linters enforce code quality and error handling (#239) - **ci**: Quality problems surface and fix themselves (#241) - **scripts**: Refuse any change to a released schema snapshot (#279) - **ci**: Pin the rust toolchain and check the minimum rust version (#284) - **deps**: Allow mit-0 and keep the two licence allow-lists in step (#287) ### Maintenance - **project**: Scaffold repository, documentation site and agent rules - **project**: Specs, roadmap as code, sprints and process checks (#16) - **roadmap**: Plan version 1.0 with specifications and ADRs (#135) - **scripts**: Cover every rule of the process scripts (#147) - **roadmap**: Titles state the outcome and are unique (#149) - **scripts**: Reproduce the roadmap on a repository with bootstrap_github (#150) - **agents**: Session hooks for formatting and documentation impact (#155) - **roadmap**: Plan checkout, PR ledger, naming rules and token savings (#169) - **roadmap**: Plan the process policy in the engine and loop changes (#187) - **roadmap**: Plan the process and system skills, agents and hooks (#206) # Contributing to Wayloop Thank you for your interest. Wayloop is in its design phase: the most useful contributions today are questions, objections and real use cases, opened as issues. ## Before you start - Read the [vision](https://salvo8519.github.io/wayloop/project/vision/) and the [architecture decisions](https://salvo8519.github.io/wayloop/project/adr/). - Look for an existing issue, or open one describing the problem before writing code. - Agents and humans follow the same rules: see [AGENTS.md](https://github.com/salvo8519/wayloop/blob/main/AGENTS.md). ## Set up Install [uv](https://docs.astral.sh/uv/), [rustup](https://rustup.rs/) and Node.js with npm. rustup installs the Rust version pinned in `rust-toolchain.toml` on the first `cargo` command, the same one CI uses (docs/en/project/conventions.md, Code quality); `just dup` installs the duplicated-code detector from `package-lock.json` with `npm ci` the first time it runs. Then: ```bash uv sync --all-groups uv run pre-commit install --hook-type pre-commit --hook-type commit-msg uv run just check ``` The pre-commit hook formats the staged files and applies the safe fixes of ruff: a commit with unformatted code stops once with the files already fixed; stage them and commit again. CI runs the same tools in check mode. `uv run just coverage` measures line coverage and needs the `llvm-tools-preview` component of rustup (`rustup component add llvm-tools-preview`). ## Working with Claude Code The project settings in `.claude/settings.json` register these hooks: - at session start, a short briefing: branch, issue, latest hand-over and its next step; - before each request, a reminder to propose roadmap changes before doing planned work; - before each edit, a released contract snapshot (`schemas/**/v.json`) cannot be changed: the next version is written instead; - after each edit, the written file is formatted (rustfmt for Rust, ruff for Python); - before the session or a subagent ends, the fast checks run on the changed files (rustfmt and clippy on the touched crates, ruff and mypy on changed Python) and send their findings back, never twice for the same findings and at most three times per session; - before the session ends, `scripts/docs_sync.py impact` lists changes that still need their documentation, and a session that committed today without a hand-over in `.agents/journal/` is asked to write it. The hooks never block on a missing tool: they report it and the work goes on. On GitHub, every pull request that is ready for review receives an automated first review against `.agents/agents/reviewer.md` and AGENTS.md; the label `docs-sync` asks Claude to bring the documentation of a pull request in line; maintainers and collaborators can mention `@claude` in issues and pull requests. All three need the repository secret `ANTHROPIC_API_KEY` and are skipped or inactive without it. ## Pull requests - One issue per pull request; the body says `Closes #`. - Conventional Commit title with a scope, for example `feat(ledger): chain events by hash`. - `uv run just check` passes locally. - English documentation changes come with the Italian translation, or the label `translation-pending`. - A fragment in `changes/` for every user-facing change, or the label `no-release-note`. - Commits are signed off (`git commit -s`), under the Developer Certificate of Origin. - A change to a script in `scripts/` that enforces the process (roadmap, sprints, commit conventions, task ids, translations) comes with a test in `tests/process/` for the rule it adds or changes. ## Licence By contributing you agree that your contribution is licensed under the Apache License 2.0. # Conventions Names and links are structured so that people and agents can follow any piece of work from the plan to the release, and an agent can take over an issue without asking how things are named. Every rule on this page is checked by a script, by CI or by both. ## The chain | Level | Identifier | Example | References | | --- | --- | --- | --- | | Milestone | `M · ` | `M1 · Engine core` | release gate | | Epic | parent issue `#` | `#22 Ledger` | milestone | | Task | sub-issue `#` | `#12 Approved specification of the ledger` | parent epic, specification | | Specification | `SPEC-`, requirement `R` | `SPEC-0003 R4` | issue | | Branch | `/-`, or `sprint/SNN/-` in a sprint lane | `feat/12-ledger-hash-chain` | issue | | Commit | `(): ` | `feat(ledger): chain events by hash [SPEC-0003 R2]` | specification, issue (trailer) | | Pull request | same format as a commit | `feat(ledger): chain events by hash` | `Closes #12` | | Merge commit | pull request title and number | `feat(ledger): chain events by hash (#57)` | pull request | | Release note | `changes/..md` | `changes/12.feature.md` | issue | | Release | tag `v` | `v0.1.0` | CHANGELOG and release notes | The GitHub number (`#12`) is the key of an issue on the tracker. It is unique, permanent, and GitHub links it automatically in commits, pull requests and comments, so branches, commits, pull requests and release notes cite it. Pull request numbers share the same sequence. The artifact identifier of ADR 0008 (`TASK-0107`) is the identity of the artifact inside the engine: it lives in the structured block of the artifact, and the engine records and checks the pair of identifier and issue number. Nothing else cites it, so the two schemes cannot drift. ## Issues - **Title**: the outcome, as a short sentence in sentence case, without a type prefix and without a full stop: `Ledger replay gives the same state on every platform`, not `feat: ledger replay` or `[FEAT] replay`. A title may start with a command name (`wayloop init creates ...`). Titles of tasks and epics are unique across the roadmap, so that a title identifies one piece of work. `scripts/roadmap.py check` enforces both rules. - **Type**: chosen with the issue form, which applies the label: `task` for planned work, `bug` for a defect, `spec-request` for a proposed capability. Blank issues are disabled. - **Area**: one `area:*` label. Areas decide which issues can run in parallel; the area list of the task form matches the `area:*` labels of the roadmap, and a test checks it. - **Hierarchy**: every task is a sub-issue of an epic, every epic belongs to a milestone and carries the label `epic`. The roadmap file `roadmap/roadmap.yaml` is the source of this structure: each task names its issue and, where one exists, its specification. Create issues with `python scripts/roadmap.py new --milestone M2 --epic "" --title ""`, which sets the milestone and labels on GitHub, links the task to its epic and adds it to the file. - **Body**: it starts with `Part of #<epic>.`, then the outcome and the advantage it brings, the scope as a checklist, acceptance criteria, the verification technique, references to specifications and ADRs, `## Depends on` with one `- #<n>` line per blocking issue, and the definition of done. Every issue under `## Depends on` is also a native blocked-by dependency. - **Checks**: CI refuses a pull request that closes an issue missing from the roadmap or not marked `done` in it, and a specification that no task references. `roadmap.py sync` copies issue states from GitHub; `roadmap.py links` checks that every planned issue has the title, milestone, labels, parent epic, parent line and dependencies of the plan. The workflow `Roadmap sync` runs both every day and on issue events. - **Plans in public pages**: the README files and every documentation page outside `project/`, in English and Italian, describe what exists. What comes next is stated only in the roadmap page, generated from the plan; a public page links it instead. A page for a part that does not exist says so in one line and links the roadmap page. `scripts/docs_sync.py claims` checks it in `just process`, pre-commit and CI: it fails on plans in prose ("will", "planned", "coming soon", "on the roadmap", a milestone number such as "M2", and the Italian equivalents) and ignores code, link targets and HTML comments. ## Status The open or closed state of an issue, plus two labels: `in-progress` when the work is claimed and a branch exists, and `blocked` with a comment that says on what. An agent that takes an issue adds `in-progress`; an agent that cannot continue adds `blocked` and its reason, or opens a question with `needs-decision`. ## Branches `<type>/<issue>-<slug>`, lower case, words separated by hyphens, at most five words in the slug: `fix/61-replay-order`, `docs/48-mcp-guide`. The type is the Conventional Commit type of the main change. One branch per issue; branches are short-lived and deleted after merge. An issue worked in a sprint lane uses `sprint/SNN/<issue>-<slug>` instead: on those branches CI also checks that the pull request changes only the files of the lane ([sprints](https://github.com/salvo8519/wayloop/blob/main/sprints/README.md)). Exempt: `dependabot/*`, `release/v*`, and `revert-<n>-*`, the branch GitHub creates for the Revert button. ## Commits ```text <type>(<scope>)[!]: <subject> [SPEC-NNNN Rk] <body: what and why, wrapped at 72 characters> Refs: #42 Docs-impact: none Signed-off-by: Name Surname <email> ``` - **Type**: `feat` (new capability), `fix` (wrong behaviour), `perf`, `refactor` (no behaviour change), `docs`, `test`, `build` (packaging, dependencies), `ci`, `chore`, `revert`. - **Scope**: required (except for `revert`), one of: engine `core`, `runtime`, `ledger`, `state`, `tracker`, `survey`, `schemas`, `security`; adapters `cli`, `python`, `typescript`, `mcp`, `plugins`; documentation and project `docs`, `i18n`, `brand`, `specs`, `adr`, `agents`, `project`, `roadmap`; build and delivery `ci`, `deps`, `release`, `scripts`, `benchmark`. New scopes are added in `scripts/conventions.py` with this page in the same pull request. - **Subject**: imperative, lower case first word, no full stop, header at most 72 characters. - **Breaking change**: `!` after the scope and a `BREAKING CHANGE:` paragraph in the body; the pull request carries the label `breaking-change`. - **Trailers**: `Signed-off-by` always (`git commit -s`); `Refs: #<n>` to link the issue; `Docs-impact: none` when the change genuinely needs no documentation. - The commit-msg hook and the pull request workflow run the same code, `scripts/conventions.py`. ## Pull requests - **Title**: a Conventional Commit header that summarises the whole change. Pull requests are squash-merged with their title, so the title becomes the commit on `main` and the line in `CHANGELOG.md`. - **Body**: the template sections, and the linked issue with a closing keyword: `Closes #42` when the pull request completes the issue, `Refs #42` when it does not. The checks read the closing keywords as GitHub does: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves` and `resolved`, in any case, with an optional colon, anywhere in the body. Trivial changes without an issue (a typo) carry the label `no-issue`. - **Branch and issue agree**: the issue number in the branch is the one linked in the body. - **One definition**: `scripts/conventions.py` owns the branch rule (`branch_issue`, `sprint_of`) and the closing keywords (`closed_issues`, `linked_issues`); the other scripts import them. The session briefing hook keeps a copy of the branch rule in shell, held equal by a test. - **Size**: one issue, one concern. A change to `wayloop-core` and an unrelated workflow change are two pull requests. - **Roadmap**: the pull request marks its task `done` in `roadmap/roadmap.yaml` in the same change. - **Merge**: the agent that opened the pull request merges it when the gate of its tier holds; changes to `crates/`, `schemas/` or an SDK wait for the maintainer's confirmation ([AGENTS.md](https://github.com/salvo8519/wayloop/blob/main/AGENTS.md#merging)). - **Stacked pull requests**: a pull request built on another one targets that branch; before it is merged it is rebased onto `main` with its own commits only, and retargeted to `main`. - **Failures of external analyses**: CodeQL, dependency review and the other external analyses are re-run first; merge waits until the failure is understood. When the failure is demonstrably on the side of GitHub, of a vendor or of a repository setting not yet enabled, and every required check is green, the merge proceeds and the pull request records why. ## Labels Labels that need judgement are added by the author; `area:*` labels are applied automatically from the changed paths. Each label below either opens or waives a check, and a test keeps this list, the workflows, the label names of the scripts (`scripts/_labels.py`) and the roadmap file in agreement. | Label | Effect | | --- | --- | | `epic` | marks a parent issue of the roadmap | | `task`, `bug`, `spec-request` | type of an issue, applied by the issue form | | `spec`, `adr`, `contract` | the issue writes a specification, an ADR or changes a contract | | `maintainer`, `needs-decision` | the issue waits for the maintainer; a question is open | | `parallel` | the task can run in parallel with others of its epic | | `in-progress`, `blocked` | status, see above | | `good first issue` | suitable for a first contribution | | `no-release-note` | waives the release note fragment for a change visible to users | | `no-docs-needed` | waives the documentation impact check | | `translation-pending` | waives the Italian translation check; the translation follows | | `no-issue` | a trivial pull request without an issue | | `breaking-change` | the pull request breaks a contract or a command | | `docs-sync` | asks the automated documentation sync for this pull request | | `maintenance` | the issue of the weekly maintenance run | ## Contract snapshots A schema under `schemas/<area>/<name>/` named `v<N>.json`, `v<N>.output.json` or `v<N>.input.json` is a snapshot ([ADR 0009](adr/0009-contract-guidelines.md), C5; [ADR 0030](adr/0030-contracts-generated-from-rust-types.md), G5). Snapshots are generated from the contract types, never edited by hand: change the type, or the registry `wayloop_schemas::contract::CONTRACTS` for a new contract or version, and run `uv run just generate`. The command writes the text that `contract::snapshot` gives, byte for byte, the history of each contract in `schemas/<area>/<name>/index.json` (`format`, `current` and, per version, its files, their SHA-256 and `introduced_in`, `unreleased` until a release), and the copies that `wayloop-schemas` embeds in `crates/wayloop-schemas/snapshots/` with their list `src/contract/embedded.rs`. A second run changes no byte. Rules, checked by `scripts/schema_snapshots.py` in `just check` (recipe `schemas`) and in CI: - `--check` fails when a committed snapshot, history, copy or list differs from the generated one, on a file under `schemas/` that is neither generated nor recorded, and on a folder of a contract the registry does not list. - A version earlier than the current one never changes. The current version, once a release holds it, changes only additively: a new optional input member, a new output member, a new `enum` value, documentation. Any other change is a new version `v<N+1>`, written beside the unchanged `v<N>`. `--diff-against <base>` classifies the changes against the merge base with `main`, and refuses a rewritten history: an earlier version changed, a released file deleted, replaced by a symlink or with another mode, a version or a contract removed, a current version gone back. - Until the first release that holds it, the current version may also change incompatibly (ADR 0030, amendment of 2026-11-20). No release holds a version when its record on `main` says `introduced_in: unreleased` and no release tag holds its file. Only a tag `v<major>.<minor>.<patch>` counts as a release, the pattern `SEMVER` of `scripts/roadmap.py`; if pre-release tags are introduced, that pattern must be extended first. `--diff-against` then allows the breaking change and still prints it as breaking, so that the pull request shows it. It runs against the updated base: a release tagged between the check and the merge is caught, because the release writes `introduced_in` on `main` and the check runs again. The site publishes `main`, so the `$id` of an unreleased version is public and the schema at that URL may change before the first release. - A released file is one that a history on `main` records, whatever its name, or one that the snapshot pattern matches. A released version record never changes, except `introduced_in`, from `unreleased` to a release, and the hashes of the files of the current version; a key a record does not define fails `--check`. - Generation refuses to write a version lower than the current one, or one that leaves a gap; versions run from 1. It also refuses a file whose name the snapshot pattern of the script and of the hook does not recognise: the generator prints every part of a contract with the name of its first file, and the script stops on a part the pattern misses. The hook `.claude/hooks/protect_contracts.py` blocks a hand edit of a snapshot that exists on `main`. The documentation build publishes `schemas/` at the URLs of the `$id` of the snapshots, with the history of every contract assembled in `schemas/index.json`. ## Release notes A change to `crates/*/src/` or `schemas/` adds one fragment `changes/<issue>.<type>.md`, with type `breaking`, `feature`, `improvement` or `fix`, unless the pull request is labelled `no-release-note`; CI runs `towncrier check` against the base branch. ## Documentation in sync - `scripts/docs_sync.py coverage`: every ADR has its row in the ADR index, its entry in the navigation and a valid status line; every specification has a valid status; every page of the navigation exists and every page is in the navigation. - `scripts/docs_sync.py claims`: public pages state no plans in prose (rule "Plans in public pages" above). - `scripts/docs_sync.py impact`: a change to the engine (every crate but the command line), the command line, the schemas, the guards of the pure crates (`scripts/check_core_io.py`, the `clippy.toml` of the workspace) or a process script comes with the matching documentation. A change that genuinely needs none is labelled `no-docs-needed`, or every commit of its branch carries the trailer `Docs-impact: none`: a waiver on one commit does not cover the others. The local check runs as a commit-msg hook, so the trailer of the commit being written applies there too. ## Code quality Linters enforce the quality of the code and how it handles errors; `just check`, pre-commit and CI run the same commands. - **Rust toolchain**: one version, pinned in `rust-toolchain.toml` at the root with the `rustfmt` and `clippy` components. rustup reads the file for every local `cargo` command, and CI installs the version written there, so a pull request fails only on its own changes and never on a lint released upstream. The weekly maintenance workflow builds, tests and runs clippy with the newest stable instead, and lists its findings in the maintenance issue. A bump is a deliberate step of the maintainer: one small `build(deps)` pull request that changes the `channel` in `rust-toolchain.toml` and fixes the new lints in the same change. The minimum supported version (`rust-version` in `Cargo.toml`) is separate from the pinned one: the CI job "Minimum supported Rust version" builds every crate with it on each pull request. - **Rust**: `cargo clippy --workspace --all-targets -- -D warnings` with the `all` and `pedantic` groups and the restriction lints of the workspace manifest that refuse a panic in the code that ships: `unwrap_used`, `expect_used`, `panic`, `todo`, `unimplemented`, `unreachable`, `indexing_slicing`, `string_slice`, `get_unwrap`, `panic_in_result_fn`, `exit` and `mem_forget`. Tests may unwrap, expect, panic and index (`clippy.toml`). A failure is a value: the error type of the core carries the code, reason and pointer of ADR 0009 (C3). - **Python** (`scripts/`, `tests/`, `.claude/hooks/`): `ruff check` with the rules of `pyproject.toml`: errors and style (`E`, `W`), likely mistakes (`F`, `B`), imports (`I`), modern syntax (`UP`), simpler code (`SIM`), ruff's own checks (`RUF`), an explicit encoding on every file read and write (`PLW1514`), and error handling: no blind `except Exception` (`BLE`), no silent `try`-`except`-`pass` (`S110`), exceptions raised and caught with care (`TRY`). `ruff format --check` keeps one format, and `mypy` in strict mode checks the types. `just python` runs the three; `just fmt` formats and applies the safe fixes. A finding is fixed, not silenced: a `noqa` or `type: ignore` needs a comment that says why. - **One source**: every rule and value is defined once and imported where it is used. The process scripts share their helpers through `scripts/_*.py`, written with the standard library only, so that hooks and workflows can import them without the project environment: `_github.py` (the repository, one call of the GitHub CLI with retries, the REST API, every page of a list), `_git.py` (tracked files, changed files, one call of git) and `_labels.py` (the names of the labels the scripts read or write, each planned in the roadmap file). The hooks run with the system `python3` and put `scripts/` on their import path. Scripts import each other by module name, as `python scripts/<name>.py` allows; the tests import the scripts and the hooks the same way and share their fixtures in `tests/process/conftest.py` (a throwaway git repository, the hooks with the scripts they need). The model of the roadmap file (`load`, `epics`, `tasks`, `depends_on` and the task tags `TAGS`) lives in `scripts/roadmap.py`; `bootstrap_github.py` and `journal.py` import it. - **Duplicated code**: `just dup` runs jscpd (pinned in `package.json` and `package-lock.json`, settings in `.jscpd.json`: blocks of at least 8 lines and 60 tokens, files up to 20 MB, generated and frozen folders left out) in `just check` and CI. The pure crates (`wayloop-core`, `wayloop-schemas`) admit no clone beyond `.jscpd-baseline.json`, which holds the five clones that issue #299 deals with and may only shrink (a test checks it); the crates, the scripts, the tests and the hooks together admit at most 1 percent of duplicated lines. A deliberate copy (an independent oracle in tests, a frozen snapshot, a hook that runs without the project environment) states its reason in a comment and has a test that keeps it equal to its source. - **Workflows**: the composite actions `.github/actions/rust-toolchain` (the channel of `rust-toolchain.toml`) and `.github/actions/python-env` (uv and `uv sync --locked`) set up the jobs; the `justfile` names the pure crates (`pure_crates`) and the Python paths (`py_paths`) once, and CI calls its recipes (`just python`, `just sprints`, `just dup`, `just mutants`) instead of repeating their commands. Problems are fixed where they appear, without the maintainer watching for them: - **Agents**: the Claude Code Stop hook `.claude/hooks/quality-gate.sh` runs the fast checks on the files changed against `HEAD` (staged, unstaged and untracked): `rustfmt --check` and `cargo clippy -p <crate> --all-targets -- -D warnings` for the touched crates, `ruff check`, `ruff format --check` and `mypy` for changed Python. It runs when the session and when a subagent stop. Findings block the end of the turn, so the agent fixes them first; the same findings never block twice in a row, and a session is blocked at most three times. The checks share a budget of 60 seconds; a check that does not finish in time, or a missing tool, is reported without blocking. - **Commits**: pre-commit applies `cargo fmt`, `ruff check --fix` and `ruff format` to the staged files. A commit with unformatted code stops once with the files already fixed: stage them and commit again. CI runs the same tools in check mode. - **Coverage**: CI runs the Rust tests instrumented by cargo-llvm-cov and the process tests with pytest-cov, and writes both line coverage tables to the job summary. The line coverage of each pure crate, `wayloop-core` and `wayloop-schemas`, must stay on its own at or above the floor in the `justfile` (`pure_coverage_floor`, 95 percent). They hold the decision logic and the contract types and perform no I/O, so every line can be tested without mocks. The floor stays below 100 because a `const fn` that runs only at compile time is counted as not covered, and because mutation testing judges the strength of the tests better than the last few percent would. `just coverage` measures locally (it needs the `llvm-tools-preview` component); `just coverage 100` tries a floor. - **Mutation testing**: every week the maintenance workflow runs cargo-mutants on `wayloop-core` and `wayloop-schemas` (`just mutants` locally). A mutant that survives means a change in the logic that no test notices; the surviving mutants are listed in the maintenance issue. - **Failures**: a failure of CI or of the documentation on `main`, or of a scheduled workflow, opens or updates one issue labelled `bug` per workflow with the failing jobs and the link to the log, and the next green run closes it (`scripts/failure_issue.py`). A fix references such an issue with `Refs #<issue>`, not `Closes`, because the green run closes it. The session briefing lists open `bug` and `maintenance` issues before anything else. - **Dependency updates**: Dependabot pull requests are merged by the session agent in pull-request triage once the required checks are green; Rust crates and ruff wait for review (`docs/en/project/dependencies.md`). ## House style No icons, emoji or decorative symbols in any file, commit message, issue or pull request. `scripts/check_style.py` enforces it. Corporate, precise English: short sentences, explicit terms, no marketing superlatives. <!-- source: https://salvo8519.github.io/wayloop/project/dependencies/ --> # Dependency policy Wayloop drives agents that write code in other people's repositories, so every dependency is part of what its users trust. This page states what is accepted, how updates arrive, when they are applied and who decides. Every tool listed is free for public open-source repositories. ## What may be added - **Core (`wayloop-core`)**: as few crates as possible, and no network, file-system, process or async-runtime crates: decision logic has no I/O (ADR 0001, ADR 0006). A new runtime dependency of the core needs an ADR that names its maintainer, its licence, its scope, the absence of I/O and a fallback if it is abandoned. Upgrades of core dependencies are always reviewed, never merged automatically. - **Runtime and adapters**: an actively maintained project with a release in the last twelve months, a licence on the allow-list of `deny.toml` and of the Security workflow, and a reason that a few lines of our own code would not cover. - **Tooling**: the same rule; development tools live in the `dev` and `docs` groups of `pyproject.toml`, or in the `devDependencies` of `package.json` for a tool published only on npm, pinned to an exact version with its lock file and installed with `npm ci --ignore-scripts`. They never reach users. jscpd 5 ships a native binary built from Rust crates; Dependency review sees the npm packages and their licences, not the licences of the crates bundled in that binary. It is accepted as a development tool that never ships. - **Licences**: two lists, one rule. `cargo deny` (`deny.toml`) checks the normal Rust dependencies; it leaves out crates used only by tests. Dependency review (the Security workflow) checks every dependency a pull request adds, development dependencies and Python packages included. Its list may hold more licences, for Python packages, never fewer: `scripts/check_licences.py` refuses a licence allowed in `deny.toml` and missing from the workflow. A new licence is added to both lists in the same change. ## How the project learns that an update is needed | Signal | Tool | Cadence | | --- | --- | --- | | New versions of crates, Python packages, npm tools and GitHub Actions | Dependabot version updates (`cargo`, `uv` with its lock file, `npm` with its lock file, `github-actions` for the workflows and the composite actions of `.github/actions`), minor and patch grouped per ecosystem | Weekly | | Known vulnerabilities | Dependabot security alerts (crates, Python packages, npm tools and GitHub Actions); `cargo deny check advisories`; `pip-audit`. CI installs the npm tools with `npm ci --no-audit` and relies on the Dependabot alerts for them | Immediate; every pull request and weekly | | A dependency with a vulnerability or a disallowed licence added by a pull request | Dependency review | Every pull request | | Vulnerable patterns in our code and workflows | CodeQL (Python, Rust, GitHub Actions) | Every push, pull request, weekly | | Supply-chain practices of the project | OpenSSF Scorecard | Weekly and on `main` | | Breakage coming with the next compatible versions | Weekly maintenance: tests with upgraded lock files | Weekly | | Tests that miss a change in the decision logic | Weekly maintenance: mutation testing of `wayloop-core` (cargo-mutants) | Weekly | | A failure of CI on `main` or of a scheduled workflow | Failure issues workflow: one issue labelled `bug` per workflow | Every completed run | | Unmaintained, yanked or wildcard crates, unknown sources | `cargo deny` | Every pull request | | Unsafe workflows: injection, permissions, persisted credentials, unpinned actions | zizmor | Every pull request | | Workflow syntax, runner labels, shell mistakes | actionlint with shellcheck | Every pull request | | Rust dependencies declared but not used | cargo-machete | Every pull request | | Duplicated code: none in the pure crates beyond a shrinking baseline, at most 1 percent elsewhere | jscpd (`just dup`) | Every pull request | | Broken links in the documentation | lychee | Weekly | | Required checks that no longer match the ruleset of `main` | `scripts/required_checks.py remote` | Weekly | A failure of the weekly maintenance opens one issue labelled `maintenance`, or updates the open one (its body with the latest report and the surviving mutants, a comment with the run); the next green run closes it. A failure of CI, Docs or Security on `main` (on a push or a schedule), or of a scheduled run of Roadmap sync, does the same with one issue labelled `bug` per workflow (`scripts/failure_issue.py`). The session briefing lists these issues first. Cargo tools pinned in the workflows (`tool: <name>@<version>` and the `cargo install --locked` fallback next to it) are not updated by Dependabot: the maintainer checks them at each weekly maintenance and updates both lines together in one `ci(deps)` pull request. ## When to update | Kind of update | When | How | | --- | --- | --- | | Security fix | Within seven days of the alert, immediately for a critical one | Dependabot security pull request, or a manual `fix(deps)` | | Patch and minor versions | Weekly, one grouped pull request per ecosystem, at least 7 days after the release | GitHub Actions and Python tools: merged by the session agent in pull-request triage once the required checks are green; Rust crates and ruff: merged after review | | Major versions | Within one month, after reading the upstream changelog | One pull request per dependency | | Rust toolchain of builds and CI (`rust-toolchain.toml`) | After a weekly maintenance run reports the newest stable, when the maintainer decides | One `build(deps)` pull request that changes the pinned version and fixes the new lints | | Rust toolchain for the minimum supported version | Only on purpose, with `rust-version` in `Cargo.toml` | `build(deps)` pull request with the reason | A release is never made with an open security alert, a failed weekly maintenance run or a dependency pull request older than one month. ## Who merges dependency updates Dependency pull requests are small (AGENTS.md, Review effort). The session agent merges a Dependabot pull request of GitHub Actions or of the Python development tools during pull-request triage (the `pr-triage` skill) once the required checks are green. Two kinds wait for review: Rust crates (`cargo`), because they change what ships, and ruff, because it is pinned to a minor range and a new minor version can change the lint rules. A merge by an agent is a normal merge, so the push workflows on `main` (CI, Docs, Security and the failure issues) run on it; a merge made by the `GITHUB_TOKEN` of a workflow would not start them. Dependabot proposes a new version only after a cooldown of 7 days (`cooldown` in `.github/dependabot.yml`): a compromised or broken release is usually yanked within that time. Security updates are not delayed by the cooldown. ## GitHub Actions are pinned to commits A tag such as `v7` can be moved to other code by whoever controls the action; a commit hash cannot. Every `uses:` names a commit with the tag as a comment; `python scripts/pin_actions.py` pins new ones and `--check` fails CI on any action left unpinned. Dependabot updates the hash and the comment together. <!-- source: https://salvo8519.github.io/wayloop/project/adr/index/ --> # Architecture decisions Each decision is recorded once, with its context, the options considered and its consequences. A decision is changed only by a new record that supersedes it. | Record | Decision | Status | | --- | --- | --- | | [0001](0001-rust-engine-thin-adapters.md) | One engine in Rust, thin adapters | Accepted | | [0002](0002-tracker-as-database.md) | The issue tracker is the database of the plan | Accepted | | [0003](0003-deterministic-ledger.md) | An append-only, hash-chained ledger written by the engine | Accepted | | [0004](0004-no-embeddings.md) | No embeddings in the product | Accepted | | [0005](0005-english-source-bilingual-docs.md) | English source, documentation in English and Italian | Accepted | | [0006](0006-synchronous-core-asynchronous-runtime.md) | Synchronous pure core, asynchronous runtime | Accepted | | [0007](0007-files-as-source-sqlite-as-index.md) | Files as the source, SQLite as a derived index | Accepted | | [0008](0008-identifiers-and-traceability.md) | Identifiers and traceability between artifacts | Accepted | | [0009](0009-contract-guidelines.md) | Contract guidelines: envelope, errors and versioning | Accepted | | [0010](0010-configuration.md) | One configuration file with layered precedence | Accepted | | [0011](0011-executors-behind-an-interface.md) | Executors behind an interface; no model calls in the core | Proposed | | [0012](0012-gates-on-the-tracker.md) | Approval gates are tracker states, not chat prompts | Proposed | | [0013](0013-worktree-per-issue.md) | One worktree per issue; lanes as the unit of parallelism | Proposed | | [0014](0014-specifications-by-capability.md) | Living specifications by capability with change deltas | Proposed | | [0015](0015-index-design.md) | Index: tree-sitter symbols and SQLite full-text search | Proposed | | [0016](0016-council-protocol.md) | Expert council: independent first round and structured report | Proposed | | [0017](0017-idempotent-issue-generation.md) | Generated issues are idempotent by stable identifiers | Proposed | | [0018](0018-language-bindings.md) | Bindings through one JSON boundary | Proposed | | [0019](0019-distribution-and-versioning.md) | Distribution channels and versioning | Proposed | | [0020](0020-plugin-and-skill-packaging.md) | Plugins and skills generated from one source | Proposed | | [0021](0021-benchmark-methodology.md) | Benchmark methodology | Proposed | | [0022](0022-threat-model.md) | Threat model: content is data, executors have least privilege | Proposed | | [0023](0023-stability-policy.md) | Stability policy for 1.0 | Proposed | | [0024](0024-tool-definitions-for-agents.md) | Tool definitions for agents: MCP and function calling from one source | Accepted | | [0025](0025-api-executor.md) | API executor for steps that do not edit code | Proposed | | [0026](0026-process-policy-in-the-core.md) | Process policy as registries, rules in the core and a ledger of results | Proposed | | [0027](0027-skills-agents-hooks-standard.md) | One standard and one source for skills, agents and hooks | Proposed | | [0028](0028-one-contract-on-every-channel.md) | One contract on every channel, translation adapters and a channel reconciler | Accepted | | [0029](0029-merge-waived-by-policy.md) | Merge of small changes waived by policy, recorded as a waiver | Accepted | | [0030](0030-contracts-generated-from-rust-types.md) | Contracts generated from Rust types, versioned snapshots with a history | Accepted | <!-- source: https://salvo8519.github.io/wayloop/project/adr/0001-rust-engine-thin-adapters/ --> # ADR 0001: One engine in Rust, thin adapters Status: Accepted · 2026-11-17 ## Context Wayloop must be fast, deterministic and usable from many places: a terminal, Python, Node, any agent through MCP, Claude Code and Codex plugins, GitHub workflows. ## Decision All decision logic lives in one Rust crate without I/O (`wayloop-core`). The CLI, the Python SDK (PyO3), the TypeScript SDK (napi-rs), the MCP server and the plugins are adapters: they translate requests and responses, and never decide. Contracts are JSON with versioned schemas. ## Consequences - One behaviour everywhere: a bug is fixed once. - A slower start than a Python-only tool. The contracts are defined before the code, so the adapters can be written in parallel. - Adapters that need new behaviour ask the core for it. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0002-tracker-as-database/ --> # ADR 0002: The issue tracker is the database of the plan Status: Accepted · 2026-11-17 ## Context Comparable tools keep the plan in folders of files of their own. The plan is then invisible to the team, and depends on the tool that wrote it. ## Decision Roadmap, epics, stories, tasks, progress, decisions and questions live in the issue tracker (GitHub first, GitLab second). Specifications live in the repository and are linked from the issues. Only session checkpoints stay local. The engine keeps a local cache of the tracker that can always be rebuilt and is never a source of truth. ## Consequences - The project stays readable without Wayloop. - Gates are asynchronous and visible to the whole team. - The engine must handle rate limits, free text in issue bodies and concurrent edits; the mitigations are described in [State in the tracker](../../concepts/state-in-the-tracker.md). - GitLab support is partial on the free tier, where dependency relations are not available. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0003-deterministic-ledger/ --> # ADR 0003: An append-only, hash-chained ledger written by the engine Status: Accepted · 2026-11-17 ## Context Agent sessions end, crash and hand over to each other. The state of the loop must survive them, and must be the same whoever reads it. ## Decision Every step produces an event appended to a JSON Lines ledger by the engine only. Each event carries the hash of the previous one. The current state is a YAML projection rebuilt from the ledger. Session summaries are JSON validated by a schema and published on the issue. Snapshots and hierarchical roll-ups bound the size of the memory over long projects. ## Consequences - The state is reproducible and testable by replay. - Model output that does not validate becomes an error event, never a corrupted state. - The local ledger is lost with the machine; the durable memory is the set of summaries on the issues. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0004-no-embeddings/ --> # ADR 0004: No embeddings in the product Status: Accepted · 2026-11-17 ## Context Many code tools index repositories with embeddings for semantic search. Wayloop needs precise answers (where a symbol is defined, who calls it, which files a specification touches), fast and repeatable. ## Decision The index is lexical (BM25) and structural (tree-sitter symbols and the dependency graph). No embedding model and no vector store are part of the product. Teams that want semantic search can connect an external tool through MCP. ## Consequences - No model to run and no store to maintain for indexing; results are repeatable. - Natural-language questions about the code are answered less well than with embeddings; the brownfield survey documentation and the map compensate for most of them. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0005-english-source-bilingual-docs/ --> # ADR 0005: English source, documentation in English and Italian Status: Accepted · 2026-11-17 ## Context Wayloop is an open-source project born in Italy. It needs an international community of contributors and wants Italian as a first-class language for its users. ## Decision Code, identifiers, commit messages, issues, specifications and the source documentation are in English. The documentation site, the README and the templates are also published in Italian. Every translation records the hash of its English source; `scripts/i18n.py check` fails when a required translation is stale or missing. The Italian glossary is in `i18n/glossary.yaml`. Artifacts of a project managed by Wayloop are written in the language chosen in its configuration. ## Consequences - One source of truth, two editions kept in step automatically. - Every change to an English page requires its translation in the same pull request, or the label `translation-pending`. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0006-synchronous-core-asynchronous-runtime/ --> # ADR 0006: Synchronous pure core, asynchronous runtime Status: Accepted · 2026-11-17 (decided by the maintainer in #10) ## Context Many development tasks are independent and can run at the same time: issues in different lanes, council opinions, documentation of separate modules, reviews. Tracker calls are slow and rate-limited and benefit from batching. At the same time, the state of the loop must remain deterministic. ## Options 1. **Everything asynchronous**, with the state machine itself built on async tasks. Concurrency bugs would reach the state, and replaying the ledger would no longer be a simple fold. 2. **An external queue** (a message broker or a database). One more service to install and operate, against the local-first goal. 3. **A synchronous pure core inside an asynchronous runtime.** The core computes the next state and the work to do; the runtime executes the work concurrently and returns results to a single writer. ## Decision Option 3. - The core stays synchronous, pure and without I/O. - The runtime (tokio) derives the queue of ready work from the state, runs workers in parallel up to a configurable limit, each issue in its own git worktree, and groups tracker calls. - One writer validates every result and appends it to the ledger in order. - Independent, non-interactive steps may use the batch APIs of model providers where they exist. - Parallel safety comes from the plan: sprint lanes declare disjoint paths, checked before the sprint starts and again on every pull request. ## Consequences - Throughput grows with independent work without giving up replayable state. - No external service to run. - The limit on parallel agents is a cost decision as much as a technical one; it is set per project. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0007-files-as-source-sqlite-as-index/ --> # ADR 0007: Files as the source, SQLite as a derived index Status: Accepted · 2026-11-17 (decided by the maintainer in #10) ## Context The ledger, the checkpoints and the session summaries must be found quickly by agents working in parallel, one per git worktree. Two storage models are common: plain files, such as JSON Lines transcripts, and an embedded SQLite database. ## Options 1. **Files only.** Readable, diffable, append-only, nothing to install. Searching many files is slow and every agent reinvents the search. 2. **SQLite as the source of truth.** Fast queries and full-text search. The data becomes binary and opaque, cannot be reviewed in a diff, and concurrent writers from several worktrees need care. 3. **Files as the source, SQLite as an index.** Every fact is written to files first; an SQLite database with full-text search (FTS5) is built from them, updated incrementally, and can be deleted and rebuilt at any time. ## Decision Option 3. - The ledger is JSON Lines, the state is a YAML projection, summaries are JSON: these files are the only source of truth. - Runtime files live in the git directory shared by every worktree, so that the orchestrator and every lane read the same data. - The index is an SQLite file next to them, with full-text search over events, rulings and summaries. It is a cache: it is never committed, never edited, and rebuilt with one command. - Agents never open the database directly. They query it through the CLI and the MCP server (`find`, `history`, `rulings`), which return compact JSON within a token budget. ## Consequences - Searches are fast, and every agent uses the same search instead of its own. - A corrupted or stale index costs one rebuild, never data. - The database is a single local file inside the engine: no server, consistent with ADR 0006. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0008-identifiers-and-traceability/ --> # ADR 0008: Identifiers and traceability between artifacts Status: Accepted · 2026-11-17 (decided by the maintainer in #4) ## Context Acceptance criteria, requirements, tasks, commits and pull requests must stay linked when files move or are renamed. ## Decision Every artifact receives a stable identifier at creation, independent of its file name: a type prefix and a sequence (for example STORY-0042, SPEC-0003 R2, TASK-0107). Commits and pull requests cite identifiers. The engine checks links by identifier, never by path. An artifact that is also an issue on the tracker (epic, story, task) has two identifiers with different roles: - the artifact identifier (`TASK-0107`) is its identity. It is written in the structured block of the artifact, survives a move to another tracker and is what the engine uses to link artifacts; - the issue number (`#12`) is the key of the tracker. Branches, commits, pull requests and release notes cite it, because the tracker links it and closes it automatically. The engine records the pair when it creates the issue and checks that it never changes. Artifacts that live only in the repository (specification, change, brief, council report) have the artifact identifier only. ## Amendments - 2026-11-17, at acceptance: the roles of the artifact identifier and of the issue number were made explicit. ## Consequences Links survive refactoring of folders. Identifiers are never reused. A rename is a change of title, not of identity. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0009-contract-guidelines/ --> # ADR 0009: Contract guidelines: envelope, errors and versioning Status: Accepted · 2026-11-17 (decided by the maintainer in #46) ## Context Wayloop is driven mainly by agents. An agent that has to guess the shape of a result, parse an English message to find the field to correct, or discover a breaking change at run time wastes turns and money. Every command must answer the same questions in the same place, from the first release. ## Decision - **C1.** One envelope for every command: { command, data, diagnostics { warnings, not_done, checks }, meta { engine_version, envelope_version, command_version, input_hash, dry_run, defaults_applied } }; nothing command-specific outside data. `input_hash` is the SHA-256, in lower-case hexadecimal, of the input serialised as canonical JSON (RFC 8785), so that the same input gives the same hash on every machine. - **C2.** Absent and null mean not given; [] means none; every default applied is listed in meta.defaults_applied as {pointer, value, reason}. - **C3.** Every refusal is {code, message, pointer, pointers, reason, expected, fix} with errors[] listing every error found in one pass, first equal to the top level; pointers follow RFC 6901 from the root of the input sent; reason is a documented enum (syntax, missing, unknown_field, duplicate, type, enum, conflict, requires, range, length, state, stale); expected lists accepted values; fix names the closest field for a misspelt key. - **C4.** Shapes agents fill well: flat objects at most four levels deep, a choice is a kind enum plus fields, no positional alignment between arrays, snake_case enum values each with a described meaning, ISO 8601 dates. - **C5.** Every command input and output schema is snapshotted as v<N>.json and v<N>.output.json; the command version is bumped on a removed, renamed, retyped or newly nullable field; a new optional field or output field is additive; clients accept enum values they do not know. - **C6.** A command that changes state takes an expected revision and refuses a stale one with reason stale. The revision is the hash of the latest event of the ledger (ADR 0003); every result that reads state reports it in `meta.revision`. A revision is stale only when an event recorded after it touches the scope of the command: its issue, or the project phase, the gates and the plan for a command on the project. The engine checks the guards again under the writer lock, so parallel lanes do not refuse each other. - **C7.** Exit codes: 0 success, 1 input error, 2 usage error, 3 environment error, 4 stopped at a gate, 5 computation or internal error. - **C8.** A new meaning gets a new error code; codes are never renamed or reused. ## Amendments - 2026-11-17, at acceptance: the computation of `input_hash` (C1) and the definition of the revision (C6) were made explicit. - 2026-11-19, decided by the maintainer with the plan of SPEC-0001 (D6): a refused result carries the error report in a top-level field `error` and has no `data` (C1); the error report gains `source`, the location of the faulty value in the repository (C3). - 2026-11-20, decided by the maintainer with the review of #256: output schemas are open (C5). An output snapshot accepts members and values it does not list: it has no `additionalProperties`; an enum of the output lists its known values with the meaning of each in its description, and a client accepts a value it does not know; a version of the output is an integer from 1, not a constant. Clients ignore members they do not know. Input schemas stay closed. The closed form of an output, used in tests to check that the engine writes only what its contract describes, is the same type generated for the input direction (ADR 0030 G2), never a file under `schemas/`. - 2026-11-17, decided by the maintainer in #233: staleness (C6) is scoped to the issue of the command, or to phase, gates and plan for a command on the project. - 2026-11-20, decided by the maintainer with the contract audit of #282: a result that failed to compute carries the error report in `error` and has no `data`, like a refused one (C1), and its errors have the new reason `internal` (C3), which is how a client tells a failure, exit code 5, from a refusal, exit code 1 (C7). `diagnostics.not_done` lists objects `{check, reason}` and `diagnostics.checks` lists check identifiers; the `reason` of an entry of `meta.defaults_applied` is a stable `snake_case` identifier, not a reason of C3, with an optional `message` for people (C1, C2). - 2026-11-20, decided by the maintainer with the review of #256 (M1): the error report gains `document`, the index from 0 of the document of the input array `documents` that an error belongs to, absent for an error of the input itself; an error of a document has its `pointer` and `pointers` relative to that document, not to the root of the input sent (C3). The pointer `""` of a refused command version, and of the default `current_command_version` in `meta.defaults_applied`, designates the context of the command, which has no place in the input (C2, C3; ADR 0028 as amended). The line of a `source` is written only when it is known (SPEC-0004 R2). ## Consequences An agent learns one contract and corrects every input error in one round. The cost is more validation code in the core and one schema snapshot per command version, checked in CI from the first command. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0010-configuration/ --> # ADR 0010: One configuration file with layered precedence Status: Accepted · 2026-11-17 (decided by the maintainer in #46) ## Context Executors, budgets, roles, limits and tracker settings must be set per project and overridden per run. ## Decision - **Project file.** `wayloop.toml` at the repository root, with a published schema, holds the settings of the project: policy (ADR 0026), budgets, roles, limits, tracker. It is committed and reviewed. - **User file.** `~/.config/wayloop/config.toml` (or `$XDG_CONFIG_HOME/wayloop/config.toml`) holds only personal keys, marked as such in the schema: executors, model routing, notification channels. A project key in the user file is refused; project rules cannot be overridden from a personal file. - **Environment.** Variables named `WAYLOOP_<SECTION>_<KEY>`, in upper case. - **Precedence**, highest first: command flags, environment variables, user file (personal keys only), project file, defaults. - **Transparency.** `wayloop config show` returns the effective configuration in the envelope of ADR 0009, with the source of every value (flag, environment, user file, project file, default). - **Secrets** are never stored in either file; the files name the environment variable that holds them. ## Amendments - 2026-11-17, at acceptance: the user file for personal keys, the naming of environment variables and `wayloop config show` were added. ## Consequences One place to review the rules of a project, and one place for each person's own choices, which never leak into the repository. Unknown keys are rejected in both files. A personal key needs its marker in the schema before it can be set per user. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0011-executors-behind-an-interface/ --> # ADR 0011: Executors behind an interface; no model calls in the core Status: Proposed · 2026-11-17 (milestone M2 · Tracker and loop; decision tracked in #60, #69) ## Context Teams use different coding agents and providers. Coupling the engine to one of them would limit adoption and make tests depend on a network. ## Decision Agents are called only through an executor interface implemented in the runtime crate. The core never calls a model. Tests use a deterministic fake executor. ## Consequences New agents are added without touching the core. The whole loop can be tested offline. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0012-gates-on-the-tracker/ --> # ADR 0012: Approval gates are tracker states, not chat prompts Status: Proposed · 2026-11-17 (milestone M2 · Tracker and loop; decision tracked in #72) ## Context A question asked inside a chat session is lost when the session closes, and nobody else on the team sees it. ## Decision Every gate is a state of the issue with a label and a question in a fixed format. Approval is an event from an authorised person on the tracker. The loop resumes from the recorded step. ## Consequences Gates are asynchronous, visible and auditable. Answering requires access to the tracker. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0013-worktree-per-issue/ --> # ADR 0013: One worktree per issue; lanes as the unit of parallelism Status: Proposed · 2026-11-17 (milestone M2 · Tracker and loop; decision tracked in #67) ## Context Parallel agents in one working tree overwrite each other's branch and index. ## Decision Every running issue has its own git worktree. Parallel work is planned in lanes that declare disjoint paths, checked before the run and on every pull request. Generated files belong to one lane only. ## Consequences Parallel agents never edit the same file. Disk usage grows with parallelism and is reported. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0014-specifications-by-capability/ --> # ADR 0014: Living specifications by capability with change deltas Status: Proposed · 2026-11-17 (milestone M3 · Living specifications and survey; decision tracked in #78, #82) ## Context Specifications written per feature stop describing the system once the feature ships. ## Decision The current behaviour lives in one specification per capability. Every change is a delta of requirements (added, modified, removed, renamed), reviewed with the code and merged into the living specification when the change closes. ## Consequences The behaviour of the system is always readable in one place. Reviews read only the delta. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0015-index-design/ --> # ADR 0015: Index: tree-sitter symbols and SQLite full-text search Status: Proposed · 2026-11-17 (milestone M3 · Living specifications and survey; decision tracked in #87) ## Context The survey needs fast, repeatable answers on code structure (ADR 0004 excludes embeddings; ADR 0007 makes files the source). ## Decision Symbols and references are extracted with tree-sitter; files are ranked by centrality in the reference graph; the searchable index is an SQLite database with full-text search, built from files, updated by file hash and rebuildable. ## Consequences Answers are deterministic and fast. Natural-language search is weaker than with embeddings, by design. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0016-council-protocol/ --> # ADR 0016: Expert council: independent first round and structured report Status: Proposed · 2026-11-17 (milestone M4 · Upstream planning; decision tracked in #92, #98) ## Context A council generated by one context anchors on its first opinion and hides conflicts. ## Decision Roles answer the brief independently in a fixed format, then read only summaries of the others, then a moderator writes a report with decisions, rejected alternatives, dissent, risks and questions. Unresolved conflicts go to the maintainer. ## Consequences Conflicts reach the person who decides. Cost is bounded by format and length. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0017-idempotent-issue-generation/ --> # ADR 0017: Generated issues are idempotent by stable identifiers Status: Proposed · 2026-11-17 (milestone M4 · Upstream planning; decision tracked in #102) ## Context Plans change and are regenerated; duplicated issues destroy trust in the tracker. ## Decision Every generated issue carries the identifier of its artifact in its structured block. Generation updates the issue with the same identifier and never creates a second one. ## Consequences Plans can be regenerated at any time. Deleting an issue by hand requires removing its artifact too. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0018-language-bindings/ --> # ADR 0018: Bindings through one JSON boundary Status: Proposed · 2026-11-17 (milestone M5 · Adapters and distribution; decision tracked in #105, #111, #112) ## Context Python and Node users need the engine as a library without a second implementation. ## Decision Python bindings use PyO3 and maturin; Node bindings use napi-rs. Both cross the boundary with the JSON contracts of the CLI, so every adapter is tested by the same contract tests. ## Consequences One behaviour in every language. A small serialization cost at the boundary. This decision is the binding-specific case of ADR 0028, which applies the same rule to every channel. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0019-distribution-and-versioning/ --> # ADR 0019: Distribution channels and versioning Status: Proposed · 2026-11-17 (milestone M5 · Adapters and distribution; decision tracked in #118) ## Context Users install from different ecosystems and must get the same version everywhere. ## Decision One version in the workspace manifest, semantic versioning, releases approved by the maintainer and published in one run to crates.io, PyPI, npm and the plugin marketplaces, with provenance attestations. ## Consequences Consistent versions across channels. A failed channel blocks the release instead of creating a split. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0020-plugin-and-skill-packaging/ --> # ADR 0020: Plugins and skills generated from one source Status: Proposed · 2026-11-17 (milestone M5 · Adapters and distribution; decision tracked in #114) ## Context Each agent reads skills and roles in its own layout; hand-maintained copies drift. ## Decision Roles and skills live in .agents/ in the open Agent Skills format. Plugins for Claude Code and Codex are generated from it, checked in CI and published to the marketplaces. ## Consequences One source for every agent. Agent-specific features are limited to what generation supports. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0021-benchmark-methodology/ --> # ADR 0021: Benchmark methodology Status: Proposed · 2026-11-17 (milestone M6 · Benchmark and hardening; decision tracked in #120, #123) ## Context Claims about cost and quality need evidence that others can reproduce. ## Decision A fixed public corpus, a baseline of the same agent without Wayloop under the same budget, repeated runs with reported spread, per-phase cost attribution, and publication of harness and raw data. Results never name other products. ## Consequences Claims are verifiable. Benchmark runs cost money and are scheduled, not run on every pull request. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0022-threat-model/ --> # ADR 0022: Threat model: content is data, executors have least privilege Status: Proposed · 2026-11-17 (milestone M6 · Benchmark and hardening; decision tracked in #125) ## Context Wayloop reads untrusted text and drives agents that can write code and call tools. ## Decision All analysed content is data. No skill or role can change global agent instructions. Executors receive the least permissions a step needs. Secrets never enter the ledger, summaries or tracker. Injection tests run in CI. ## Consequences Safer defaults; some steps need explicit permission grants by the maintainer. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0023-stability-policy/ --> # ADR 0023: Stability policy for 1.0 Status: Proposed · 2026-11-17 (milestone M7 · Version 1.0; decision tracked in #131, #132) ## Context Users and integrators need to know what can change after 1.0. ## Decision From 1.0 the JSON contracts, error codes, configuration keys and CLI commands follow semantic versioning: breaking changes only in a major version, with one minor version of deprecation warnings first. ## Consequences Integrations stay working across minor versions. Mistakes in contracts are fixed only with a deprecation cycle. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0024-tool-definitions-for-agents/ --> # ADR 0024: Tool definitions for agents: MCP and function calling from one source Status: Accepted · 2026-11-17 (decided by the maintainer in #46) ## Context An agent needs more than the list of commands: how to call each one, which parameters, which values each enum accepts and what they mean, and whether the call changes anything. Tool schemas are read by many clients and model providers, and some accept only a subset of JSON Schema. ## Decision Tool definitions are generated from the command schemas, never written by hand. Every definition: is inlined without $ref; uses one type per type keyword, with an optional value written as anyOf of the type and null; carries the meaning of every enum value in the field description; carries a minimal and, where useful, a maximal input example taken from golden cases; states units and formats in descriptions; carries annotations readOnlyHint, destructiveHint and idempotentHint, and _meta with the command version and status. A compact profile removes only annotations, never a validation keyword. A portable variant serves providers with limited JSON Schema support. Errors are returned with isError and the whole error report as structured content. CI drives the MCP server with the MCP Inspector in strict mode and fails on a single warning. ## Consequences Every agent and every provider sees the same contract and can correct a call in one round. Each provider format becomes a contract to test. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0025-api-executor/ --> # ADR 0025: API executor for steps that do not edit code Status: Proposed · 2026-11-17 (milestone M4 · Upstream planning; decision tracked in #97) ## Context Some steps (council roles, critic, review of a plan, triage of events) only read and write structured text. Running them through a full coding agent is slow and expensive, and some teams need local models for privacy. Embedding a general agent framework would bring a second orchestrator, a foreign runtime and its decisions into the engine. ## Decision The runtime crate gains an API executor behind the same executor interface (ADR 0011): a bounded tool-use loop against an OpenAI-compatible or Anthropic endpoint, local models included, with the Wayloop commands as its only tools and every result validated by schema. It is used only for steps that do not edit code; code-editing steps stay with coding agents. No agent framework is embedded; frameworks can drive Wayloop from outside through the SDKs and the MCP server. Credentials are read from the environment, never stored. ## Consequences Council and review steps become cheaper, parallel and usable with local models. The engine keeps deciding the process; the API executor is one more executor to test with recorded sessions. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0026-process-policy-in-the-core/ --> # ADR 0026: Process policy as registries, rules in the core and a ledger of results Status: Proposed · 2026-11-17 (milestone M2 · Tracker and loop; decision tracked in #171) ## Context This repository keeps its process traceable with scripts around the product: commit and branch conventions, label waivers (release note fragments, documentation impact, translations, issue links), a registry of labels checked by tests, roadmap consistency and tracker links, sprint lanes and required checks. Wayloop promises the same discipline to every project it runs, so the rules must become a capability of the engine, not a template to copy. Three questions decide the design: where the rules and their lists live, where they are evaluated, and what is remembered about each evaluation. Options considered: 1. **Rules in the ledger.** The ledger is append-only history (ADR 0003). Rules must be edited, reviewed in a pull request and read in one place; deriving them from events would make the current policy a replay result instead of a file a person reads. Rejected as the source of rules. 2. **A rule language or user scripts.** Flexible, but evaluation would depend on user code: not deterministic across machines, a security surface (ADR 0022), and a second language to document. Rejected for 1.0; an external command returning the JSON envelope remains possible later as an extension point. 3. **Rules in the core, parameters in a registry, results in the ledger.** Chosen. ## Decision - **Registry (source of the lists).** One reviewed file, `wayloop.toml` under `[policy]`, with a published schema, declares: labels with their role (type, area, status, waiver, gate), commit types and scopes, areas with their paths, required checks, and the rules enabled with their parameters and waivers. Its defaults are the policy of this repository. Every derived file (labeler configuration, issue form areas, required checks list, the labels table of the conventions page, the labels on the tracker) is generated from it and checked against it. - **Rules (decision).** Each rule is a pure function in `wayloop-core`: input is a snapshot assembled by adapters (changed paths, commit messages, pull request title, body and labels, plan, tracker state, workflow definitions); output is the error report of ADR 0009 with pointer, reason and fix. A rule declares the paths it applies to, the evidence it requires and the waiver that lifts it (a label or a commit trailer, optionally with a required reason). Adapters fetch data; they never decide. - **Ledger (memory).** Every evaluation on a pull request and every waiver used is an event: rule, result, pull request, commit, author, reason. Waivers become auditable, and a rule waived beyond a threshold produces a reconciliation proposal (SPEC-0007). - **One command.** `wayloop check` runs the whole policy, offline or with the tracker, in the JSON envelope; a reusable CI workflow runs it. This repository migrates from its Python scripts to the engine; the scripts' tests become fixtures that the engine must pass. ## Consequences The policy is one file to read and one command to run, identical locally and in CI, for every project. Drift between labels, workflows and documentation is prevented by generation instead of detected by tests. Waivers carry a history that can change the policy. New kinds of rules need a release of the engine until the extension point exists; the defaults must stay strict enough for this repository and loose enough to adopt in an existing project, so every rule can be disabled in the registry with a recorded reason. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0027-skills-agents-hooks-standard/ --> # ADR 0027: One standard and one source for skills, agents and hooks Status: Proposed · 2026-11-17 (milestone M0 · Foundations; decision tracked in #191) ## Context Wayloop needs two families of skills, agents and hooks. The process family runs the development of this repository. The system family ships with the product and is called by the engine at each step of the loop, in the projects of its users. Both must work with Claude Code, Codex and the other coding agents that read the open Agent Skills format or an `AGENTS.md` file. A survey of widely used skill and agent collections shows the same lessons: descriptions that state when to use the skill decide whether an agent picks it; deterministic commands before judgement make results repeatable; reviewers that only read and run as a separate agent catch what the author misses; hooks that block on a missing tool break sessions; hand-written copies per agent drift. ## Decision - **One source.** Process skills and agents live in `.agents/skills/` and `.agents/agents/`; system skills and agents live in `plugins/skills/` and `plugins/agents/` from M5. Every copy for a specific agent (Claude Code, Codex, Cursor, Copilot, Gemini CLI and others) is generated and checked (`scripts/sync_agents.py`, #168). - **Skill format.** Agent Skills `SKILL.md` with `name` and a `description` that names the action and starts its trigger with "Use when". The body has, in order: what the skill produces; numbered steps, with deterministic commands before judgement; stop conditions and the questions that go to the maintainer; the report, which always states what was done, what was not done or not verified, and the risks. A skill reads and writes only what its steps name, and never changes the global instructions of an agent. - **Agent format.** `name`, a "Use when" `description`, and the tools it may use, least privilege first: reviewers, auditors and explorers are read-only. The body states what it reads, what it writes, what it never does, its output format, and to whom it hands off. An agent never reviews its own work: review runs in a different agent, of another vendor when one is configured (SPEC-0008). - **Hook format.** One script per purpose, registered per event (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop). A hook calls a deterministic command; it never blocks on a missing tool, it reports it; it exits 2 only to send a precise message back to the agent. Every hook is tested on real input. - **Checks.** `scripts/check_agents.py` validates front matter, the "Use when" trigger, the required sections, a size budget in tokens, references to commands and files that exist, and the registration of every hook. CI runs it with the mirror check. - **New skills and agents** are added by a pull request with a behavioural case: a small input and the expected result. Unused ones are proposed for removal. ## Consequences Any agent finds and uses the same skills; reports have the same shape whatever skill wrote them; drift between agents is impossible by construction. Writing a skill costs a behavioural case and a pass of the check. Agent-specific features that the generators do not support are not used. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0028-one-contract-on-every-channel/ --> # ADR 0028: One contract on every channel, translation adapters and a channel reconciler Status: Accepted · 2026-11-17 (decided by the maintainer in #231) ## Context Wayloop is reached through many channels: the command line, the Python and Node SDKs, the MCP server, the function-calling formats of model providers, and the plugins and skills of coding agents. ADR 0001 keeps decision logic in the core and ADR 0018 makes the bindings cross a JSON boundary, but neither states what every channel must return, and nothing checks it. A channel that decides, filters or cuts a result gives a different answer for the same request, and the difference is found by a user. A second contract per channel would be a maintenance cost that grows with every channel and drifts from the first. ## Options 1. **A contract per channel**, each tested on its own. Many contracts to keep in step; the channels drift. 2. **One contract and adapters kept thin by review.** Cheap, but the rule is enforced by discipline only. 3. **One contract, adapters that are translation functions only, and a channel reconciler that checks every channel against the engine.** ## Decision Option 3. - **One contract.** The command schemas under `schemas/` (input, and output in the envelope of ADR 0009) are the only contract. Everything a channel exposes is generated from them (ADR 0024) and never written by hand. - **One entry point.** The core exposes one function: command, canonical input and context in, envelope out. Every channel calls it. - **Adapters are translation functions.** Each channel has one translation from its native form (arguments, a Python dict, a JavaScript object, an MCP tool call, a provider function call) to the canonical input, and one inverse from the envelope to its native form (exit code, typed exception carrying the envelope, MCP error result carrying the envelope). An adapter never decides, filters, reorders or cuts a result. - **Channel settings are engine parameters.** Output budget, read-only mode and dry run are part of the context passed to the entry point; their effect is computed by the engine and reported in `meta.defaults_applied` and `diagnostics`. - **Parity.** The same input and the same context give the same envelope, byte for byte in canonical JSON (RFC 8785), on every channel and platform. The envelope therefore holds no value that depends on the machine or the moment: no clock time, host name or absolute path. - **Channel reconciler.** One component sends every golden contract case through the translation of each channel, rebuilds the canonical envelope from the native output with the inverse translation, and compares it with the envelope of the engine. A difference fails with the channel and the JSON pointer. It runs in CI as a required check and locally with one command. ## Amendments - 2026-11-20, decided by the maintainer with the review of #256: the version of a command is not in its input. The channel passes the requested version in the context of the entry point; when it requests none, the engine runs the current version and lists it in `meta.defaults_applied`; a version the engine does not run is refused with the code `command_input`, reason `enum`, and the known versions in `expected` (SPEC-0004, Errors). The command line passes it with `--command-version <n>`. ## Consequences - A new channel costs one translation function and its inverse; the cases and the reconciler are shared. - Logic that slips into an adapter is found in CI, not by a user. - Some features usually built in adapters, such as truncation to a token budget, move into the engine. - Events and results must carry clock times and paths outside the envelope, or as values the input supplies. - ADR 0018 becomes the binding-specific case of this decision. <!-- source: https://salvo8519.github.io/wayloop/project/adr/0029-merge-waived-by-policy/ --> # ADR 0029: Merge of small changes waived by policy, recorded as a waiver Status: Accepted · 2026-11-17 (decided by the maintainer in #233) ## Context Constitution principle IV makes every approval state a gate that the loop cannot pass. This repository already works otherwise for small changes: the agent that opens a pull request of tier small (documentation, tooling, CI) merges it when its checks are green, and only engine, adapter and contract changes wait for the maintainer. Without a decision, the engine has two bad choices: stop the loop at every small change, or record a merge approval by a person who did not act. The ledger is the audit record (ADR 0003), so it must say what actually happened. ## Options 1. **Every merge is a person's gate in version 1.** Honest, but it stops the loop at every change and differs from how this project is built. 2. **A standing approval recorded as the maintainer's approval at each merge.** Convenient, but it puts in the ledger an act that no person performed. 3. **A waiver by policy, recorded as a waiver.** The project policy names the tiers whose merge is not an approval state; the engine records that the gate was waived and by which policy. ## Decision Option 3. - The project policy may waive the merge gate for tier `small` only. Tiers for engine logic, adapters and contracts always keep the merge gate. - The tier is computed by the engine from the paths changed on the branch, as observed in git, never from an agent's report. - When the merge gate is waived, the engine records `gate_waived` with the policy revision and the person who approved that revision. It never records a waiver as a person's approval. - A policy change that adds a waiver, widens tier `small` or relaxes a limit opens a gate of kind `configuration`, which only a recorded approver can resolve. A change that narrows applies at once. - Constitution principle IV is amended to state this exception. ## Consequences - The loop does not stop at small changes, and the audit record stays true. - An agent cannot widen its own autonomy: every widening passes a person. - The tier rules become part of the contract of the policy (SPEC-0021) and of the state machine (SPEC-0002). <!-- source: https://salvo8519.github.io/wayloop/project/adr/0030-contracts-generated-from-rust-types/ --> # ADR 0030: Contracts generated from Rust types, versioned snapshots with a history Status: Accepted · 2026-11-20 (milestone M0 · Foundations; decided by the maintainer in #291: options 3, (a), (ii) and (B)) ## Context The contracts of Wayloop (ADR 0009, ADR 0028) are hand-written JSON Schema files under `schemas/`, interpreted by the core over a documented subset (plan of SPEC-0001, D5). The first command and the first artifact, in the pull request of #256, show the cost: the error report, the source of an error, the origin of a document and the definition of a status are written again in every file that needs them, by hand, in two directions (closed inputs, open outputs). Each copy can drift from the Rust types that the core fills and from the other copies, and only review finds it. The number of files grows with every command, every artifact type and every version. The maintainer asked, on 2026-11-20, for contracts that are maintainable, with every pattern defined once, built by nesting small types into larger ones, and versioned as Fairmark versions its method schemas, so that people, systems and agents can rely on them. The maintainer chose the Rust types as the single source, as in Fairmark (ADR 0003 and ADR 0009 of Fairmark), and not hand-written JSON fragments. D5 of the plan of SPEC-0001 rejected types as the source for two reasons: a refactor of a type would change the contract silently, and the generated shapes would follow the generator rather than C4. Both are answered below by a check, not by discipline: the committed snapshot is the contract of record and CI fails when the generated schema differs from it, and the generator checks the subset and the shape rules of C4. D5 stays right on one point: the core keeps validating documents with its own interpreter, so that every error is reported in one pass with the reasons of C3. Serde deserialisation into the types never replaces it. ### Options 1. **Hand-written schemas, shared fragments by `$ref` across files.** Fewer copies, but the interpreter allows only local references, tool definitions must inline everything (ADR 0024), and the Rust types still drift from the files. 2. **Hand-written schemas assembled from fragments by a script.** Removes the copies in JSON; the types remain a second source, checked against the files only by tests. 3. **Rust types as the source; snapshots generated, committed and checked.** One definition per pattern, shared by the core, the schemas, the tool definitions and the documentation. Needs a schema derive in a pure crate and a set of rules that keep the output inside the subset. Chosen by the maintainer. For where the derive lives: - **(a) `schemars` as a normal dependency of `wayloop-schemas`**, on its allowlist. Simple; the derive is compiled into the shipped crate although only the generator calls it. - **(b) The derive behind a cargo feature** (`cfg_attr` on every type and attribute). `scripts/check_core_io.py` resolves the pure crates with `--all-features`, so the feature still needs the allowlist or an exception in the check; every contract type carries twice the attributes. - **(c) Schemas implemented in a separate generator crate.** The orphan rule forbids deriving for types of another crate; this means hand-written implementations, which is option 1 in Rust. For the history of versions: - **(i) One committed `schemas/index.json`**, as Fairmark had at first. Fairmark replaced it (Fairmark ADR 0017): two pull requests that add two contracts both rewrite it and conflict, which serialises parallel lanes. - **(ii) One manifest per contract folder** and an assembled view, as Fairmark does today. For changes to a version already on `main`: - **(A) Byte-immutable**, the current rule (`scripts/check_schemas.py`, conventions page, Contract snapshots): every change, additive or not, is a new version. - **(B) As Fairmark:** earlier versions are byte-immutable; the current version may change additively only, as C5 defines additive, and a classifier refuses any other change. ## Decision Option 3, with (a), (ii) and (B). ### G1. One source: the types of `wayloop-schemas` - Every contract type lives in `wayloop-schemas` and derives `serde::Serialize`, `serde::Deserialize` and `schemars::JsonSchema`. Its doc comments become the descriptions of the schema. The generator refuses a type, a member or an enum value without a description. A description states the meaning and, for a number, its unit or its origin (from 0, from 1); the presence is checked by the generator, the content by the contract-auditor role. - Each pattern is defined once and nested: - `Envelope<D>`: one generic envelope (C1), where `D` is the data type of one command; `Diagnostics`, `NotDone`, `Meta` and `DefaultApplied` inside it. - `Error`, `ErrorReport` (the first error and `errors`), `Source`, `Reason`: defined once, used by the envelope of every command and by `diagnostics.warnings`. - One input type and one data type per command (`ValidateInput`, `ValidateData`). - Artifact types built from one common type, `Common<Id, Status>`, holding the members every artifact has (`kind`, `schema_version`, `id`, `title`, `status`, `language`, `superseded_by`), with the identifier type and the status enum of the kind as parameters. The constants `kind` and `schema_version` come from the registration of the contract (G5), not from each type. - Identifier newtypes (`BriefId`, `TaskId`, and so on), numbers with their bound (`IssueNumber`, `Line`) and `ProjectPath`: one type per value form, used wherever the form appears. - Composition by `#[serde(flatten)]` is allowed for plain structs only, and a test proves that the generated schema merges their members into one object. No contract type uses `deny_unknown_fields`, which serde does not support with `flatten`: closedness is decided by the direction of the contract (G2). - After the interpreter has accepted a document, deserialising it into its type must succeed; a failure there is an internal error (reason `internal`) and a defect. A test checks every golden contract case both ways: the serialised value of a type is accepted by its schema, and a document the schema accepts deserialises into the type. ### G2. What the derive cannot express, written once One module of `wayloop-schemas`, `contract`, holds every rule the derive does not produce, as `schemars` settings, attributes or transforms. No JSON is edited after generation. | Need | Where it is written | | --- | --- | | Conditional requirements (`superseded_by` required when `status` is `superseded`) | A `#[schemars(transform = ...)]` attribute on the type that calls one helper of `contract::rules`; the helper writes the `allOf` of `if` and `then` of the subset | | Named formats | One enum `Format` in `wayloop-schemas` listing every named format; each value-form newtype implements `JsonSchema` by hand, once, with `type: string` and its format. The core's format checker matches on the same enum, so a format the generator emits and the core lacks does not compile | | Integer bounds | On the newtype (`#[schemars(range(min = 1))]` or a non-zero integer type); the bound of plus or minus (2^53 - 1) stays a rule of the interpreter, not of each schema | | Closed inputs, open outputs | A transform applied by the generator by direction: every object of an input schema gets `additionalProperties: false`; output schemas get none (C5 as amended on 2026-11-20) | | Absent, not null (C2) | Settings: an `Option` adds no `null` type and no `nullable`; optional members use `skip_serializing_if` and are left out of `required` | | Enum values with their meaning | A transform turns the `oneOf` of documented constants into `enum`, and appends the meaning of each value to the description of the member, as ADR 0024 requires | | Any JSON value (`fix`, `value`) | A transform turns the boolean schema `true` into an object schema with its description | | Integer `format` values such as `uint32` | Removed by a transform; the type and the bounds remain | A construct that none of these covers is not worked around: either a type changes to use a covered form, or the subset of the interpreter is extended by a reviewed change of the core with its tests and the architecture page. ### G3. The generated output stays inside the subset - Draft 2020-12 only, references local to the file (`#/$defs/...`), no `pattern`, no `null` type, no `uniqueItems`, no `default`, no format the core does not implement. Contract types therefore use `Vec`, not sets; defaults are applied by the core and reported in `meta.defaults_applied` (C2), never written as `default` in a schema. - The subset has one definition: the loader of the core (`wayloop_core::schema`). The generator loads every schema it produces with it and fails on the first refusal; a test of the core loads every embedded snapshot, of every version. - The generator also checks C4 where it is mechanical: at most four levels of objects, and an enum value for every choice. - The test-only validator of the core (the oracle) checks that every generated schema is a valid draft 2020-12 schema. ### G4. Where generation runs, and purity - `schemars` is a normal dependency of `wayloop-schemas` (option (a)), without the `preserve_order` feature, added to the allowlist of both pure crates in `scripts/check_core_io.py` with every crate it reaches (expected: `schemars`, `schemars_derive`, `serde_derive_internals`, `dyn-clone`, `ref-cast`, `ref-cast-impl`; the exact list is fixed by the task with the output of `cargo tree`). It performs no I/O. Dependency rule (`dependencies.md`): maintainer Graham Esau, licence MIT, scope limited to deriving schemas, no I/O; to be confirmed by the security-reviewer role with `cargo deny`. Fallback if it is abandoned: the committed snapshots stay the contract, and the trait can be implemented by hand or by a fork without changing a file under `schemas/`. - No `preserve_order`: with cargo feature unification it would turn on `preserve_order` of `serde_json` in the core, change the iteration order of every map the core reads, and add `indexmap` and `hashbrown` to the allowlists. The core visits members in the byte order of their keys; snapshots are written with keys in byte order too. Members of a snapshot are therefore listed alphabetically; `required` keeps the order of declaration. - The generator is a binary of a new workspace crate, `wayloop-schemagen`, not published, at the adapter level of the crate layout (it may depend on `wayloop-schemas` and `wayloop-core`). It writes nothing: it prints one JSON document with every current schema of the registry. The runtime and the command line never generate schemas; they use the snapshots embedded with `include_str!`. ### G5. Versioning as Fairmark - One registry list in `wayloop-schemas`: each contract names its area (`artifacts`, `inputs`, `commands`, `envelope`), its name, its current version and its types. The generator, the embedded snapshots and the kinds of the core are built from this list, and a test checks that the folders under `schemas/` match it. - Files: `schemas/<area>/<name>/v<N>.json`; for commands also `v<N>.output.json` (the envelope with the data of that command, self-contained); for the hand-over also `v<N>.input.json` (SPEC-0001). `$id` is the published URL of the file, as today. - History: `schemas/<area>/<name>/index.json` per contract (option (ii)), with `format`, `current` and, per version, the files, their SHA-256 and `introduced_in` (`unreleased` until the release stamps it), in the record shape of Fairmark. One function assembles the view `schema_history()`; the documentation build publishes it as `schemas/index.json` and the release attaches it. - Changes (option (B)): a version earlier than the current one never changes; the current version may change only additively under C5 (a new optional input member, a new output member, a new enum value of an output); any other change is a new version `v<N+1>`. The current version never goes back, a contract is never removed. Before a version reaches `main`, it may change freely. - An earlier version stays reproducible from its snapshot, not from Rust types: the frozen file is authoritative and is embedded for validation of documents and requests of that version (SPEC-0001 R16; the command version in the context of the entry point, ADR 0028 as amended). Moving from one version to the next is a pure function on JSON values in the core. Old types are not kept. - The generator writes only the current version and refuses to rewrite an earlier one: it stops with the name of the contract and asks for a version bump. ### G6. One command, one check - `uv run just generate` runs `wayloop-schemagen` and `scripts/schema_snapshots.py`, which writes the snapshots and the manifests of the current versions. It is deterministic (keys in byte order, two-space indentation, a final newline, UTF-8 without escapes) and idempotent: a second run changes no byte. - `scripts/schema_snapshots.py` takes over `scripts/check_schemas.py`, so that one script holds every snapshot rule: `--check` fails when a committed snapshot or manifest differs from the generated one; `--diff-against <base>` classifies the change of the current version (additive or breaking, as the classifier of Fairmark does, with the open-output rule of C5) and refuses a rewritten history. The hook `.claude/hooks/protect_contracts.py` keeps the same file pattern, tested against the script. Both run in `just check` and in CI. - Tool definitions (ADR 0024) are generated from the snapshots, not from the types, so that the definition of an earlier version is rebuilt from its frozen file. The types are therefore their source too, through one step. ### G7. Migration 1. This record, accepted by the maintainer. 2. The generator task (#291 follow-ups below): dependency and allowlist, `contract` module and registry, `wayloop-schemagen`, `schema_snapshots.py`, the error report and the envelope moved to the derive. The interpreter must accept open output objects before the first output snapshot is generated; that change of the core comes from the branch of #256 into this task, or lands first on its own. 3. The branch of #256 is rebased: its hand-written `schemas/artifacts/brief/v1.json` and `schemas/commands/validate/v1.json`, `v1.output.json` are replaced by the generated ones before their first merge, so no hand-written snapshot is ever released. ## Amendments - 2026-11-20, security review of #301 (G4): the crates reached by `schemars` are those expected, confirmed by `cargo tree`. `ref-cast` has a build script that runs `rustc --version` and writes into `OUT_DIR`; nothing runs at run time. `dyn-clone` and `ref-cast` contain confined `unsafe` (the clone of a trait object, a cast between `repr(transparent)` types), reviewed and accepted. The features of `schemars` are declared explicitly (`default-features = false`, `derive` and `std`), so that a change of its defaults upstream cannot widen them. - 2026-11-20, implementation of #294 (G4, G5, G6): a crate embeds with `include_str!` only files inside its own folder, since `cargo package` packs only that folder. `just generate` therefore also copies every snapshot of every version, byte for byte, into `crates/wayloop-schemas/snapshots/`, and writes `crates/wayloop-schemas/src/contract/embedded.rs`, the list `contract::EMBEDDED` that embeds the copies; `--check` fails when a copy or the list differs from what generation writes. The snapshots under `schemas/` stay the contract of record. The envelope is the contract `envelope/result`: the envelope of the result of every command, at the version of `meta.envelope_version`. The generator also prints every part of a contract with the name of its first file, so that the file pattern of the script and of the hook is checked against the registry. A released file is one that a history of the base records, or that the pattern matches; a released version record never changes, except `introduced_in` from `unreleased` to a release and, for the current version, the hashes of its files. Rule (B) is classified conservatively: besides the cases of C5, any change of a keyword other than `properties`, `required`, `items`, `$defs`, `enum` and the annotations is breaking, `allOf` and `$schema` included; a new `enum` value is additive in both directions, as in Fairmark. - 2026-11-20, with the rebase of #256, subject to the approval of its pull request by the maintainer (G2): in the input direction the generator closes every object that declares its members (`properties`); an object that declares none is a free object, a document whose schema is another one (the documents of `validate`, checked by the schema of their kind, and the map of their lines, checked by the core), written by hand with `value::free_object_schema` and left open. The free objects are declared in one list, `FREE_OBJECTS` of the checks of the generator, which refuses any other open object of an input, a map derived by `schemars` included. The generator also drops a definition that no reference reaches, such as the type of `kind` once a rule makes it a constant. The line of a `source` is written only when it is known (SPEC-0004 R2): a breaking change of `envelope/result` v1, which no release holds, made under the amendment below. - 2026-11-20, decision of the maintainer (G5, G6): a version that no release holds may change incompatibly until the first release that holds it; from that release it is immutable, and rule (B) applies in full. This replaces the last sentence of G5, "Before a version reaches `main`, it may change freely". No release holds a version when its record on the base says `introduced_in: unreleased` and no release tag `v<semver>` holds its file. `schema_snapshots.py --diff-against` allows a breaking change of such a current version and still reports it as breaking, so that the pull request shows it; an earlier version never changes, released or not. Residual risk: the documentation site publishes `main`, so the `$id` of an unreleased version is public, and the schema at that URL may change before the first release. A reader that depends on it before a release accepts that risk. ## Consequences Positive: - Each pattern (error report, source, envelope, common artifact members, identifier forms) is written once; a new command or artifact type is a data type, one registry line and a generated file. - The core, the schemas, the tool definitions and the documentation read one definition; a disagreement between a type and a snapshot fails CI. - The history is per contract: parallel lanes that add different contracts do not touch the same file. - Every published version stays available, identified by its URL and its hash. Negative: - A pure crate gains a proc-macro dependency and its crates on the allowlist, compiled into the shipped crate though used only by the generator. - Snapshots list members alphabetically, which reads less naturally than the hand-written order. - A refactor of a contract type can fail CI on a snapshot that only looks unrelated; the failure names the contract and the pointer, and the fix is a version bump or a revert. - Rule (B) relaxes the byte immutability of the current version: a cached copy of the current version can differ from a later one by additive changes; the history records each hash. Follow-ups: - Amend the plan of SPEC-0001 (D5 and the section on schemas and their interpreter), the architecture page (the schema interpreter, the crate layout, the allowlists), the conventions page (Contract snapshots, under rule (B)) and the dependency policy, each in the task that changes the behaviour it describes. - The documentation build publishes `schemas/` at the URLs used as `$id`, and the assembled history. <!-- source: CHANGELOG.md --> # Changelog All notable changes to Wayloop. Generated from Conventional Commits by git-cliff; do not edit by hand. <!-- source: RELEASE_NOTES.md --> # Release notes What changes for users in each version of Wayloop, in plain language. The technical history of every change is in the [changelog](https://salvo8519.github.io/wayloop/project/changelog/). On the documentation site, the first section lists the changes not yet released. <!-- release notes start -->