Skip to content

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.

Status

This page describes the design recorded in ADR 0002. 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.

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.