Start with a delivery scenario
+Suppose you tell an agent: “Deliver a bulk export feature. It must handle large datasets without exposing another user’s data. Development, testing, and documentation may continue, but ask me before the production release.”
+After a while, you usually care less about how many tools the model called than about five questions: What remains before the goal is met? Who is working on it? What can continue? What must wait? Why should anyone believe it is done? The LoopX board organizes information around those questions.
+This article uses that synthetic scenario to explain the full foundation. We will read one card, follow it into a collaboration that can be handed off and recovered, then return to four advanced questions for agent-facing Kanban. Here, Kanban means a board-shaped collaboration interface, not a redefinition of the full Kanban method.
+Goals, tasks, ownership, gates, and evidence each have their own identity and rules. The board arranges them into columns, lanes, and details; the control plane receives and validates legal operations. Screen layout does not become a new permission or source of truth.
The core objects in one diagram
+These concepts are not a form that must be filled all at once. Start with the goal and work items. Express collaboration, risk, concurrency, or recovery only when they arise, through the corresponding contract. A local single-agent Goal can remain simple; a multi-agent Goal reuses the same core objects.
+
| Concept | Question it answers | Bulk export example |
|---|---|---|
| Goal | What must ultimately be achieved, and which constraints must survive? | Deliver a usable, secure, verifiable bulk export. |
| Acceptance | What must be observed before the outcome is accepted? | Large-volume behavior, permission isolation, and the usage path are validated. |
| Todo | What is the next deliverable piece of work or explicit wait? | Implement export, review independently, validate integration, release. |
| Claim | Which agent is responsible now? | A development agent claims implementation; a reviewer claims review. |
| Lease | When the mode is enabled, which execution is valid, for how long, and within what scope? | The owner, expiry, version, and write scope of one controlled execution. |
| Gate | Which decision or authority is missing, and exactly what does it block? | Release confirmation blocks release, not independent testing by default. |
| Evidence | What supports a judgment, and which version does it apply to? | Test results, review conclusions, and artifact references for candidate revision A. |
| Lane | How is work grouped and selected from the current agent’s or operator’s perspective? | Runnable, monitor due, awaiting a decision, owned by someone else. |
| Shared authority state | Under concurrency, which rule-protected state counts? | The agreed Todos, claims, leases, and their commit receipts. |
The goal sets direction; work items carry action; claims express responsibility; leases constrain execution occupancy; gates constrain legality; evidence supports judgment. They connect to one another, but none substitutes for another.
+Goals and Todos: separate the outcome from the current plan
+A Goal is the control plane’s outcome boundary. It has a stable goal_id and connects current state, work items, constraints, and history. One Git repository may serve several Goals, and one Goal may span several repositories. Repository location should not replace goal identity.
A Todo is an identified unit of work inside the Goal and has a todo_id. A title such as “fix export” is not enough: whoever takes over also needs the concrete action, acceptance, dependencies, owner, and permitted scope. Editing a title should not turn the Todo into a different task; when direction changes, supersession relationships should preserve the lineage.
Goal: Deliver bulk export
+Acceptance: permission isolation is correct; large datasets work;
+ a user can complete an export by following the documentation
+Constraints: development and validation are allowed;
+ production release requires confirmation
+
+Todo A: Implement export and basic tests
+Todo B: Review the candidate independently; the author may not self-review
+Todo C: Validate large-volume behavior and permission boundaries
+Todo D: Release the accepted candidate after the release decisionThis is an explanatory work record, not an executable CLI payload. A through D are the current plan, not the Goal itself. If review reveals a simpler approach, some Todos can be replaced while the outcome and confirmed constraints remain.
+With multiple agents, a per-Agent Vision adds the direction each peer currently owns, its acceptance, and the triggers for replanning. It is a bounded execution-direction record—not another Goal and not a grant of global administration to one agent. See Work graph, authority, and peer collaboration for the foundation.
+Cards, states, and lanes: one body of work, several useful readings
+
claimed_by alone.Scroll horizontally on narrow screens; select the image to open it full size. All diagrams use synthetic examples.The front of a card is a good place for the work name, priority, owner, key waits, latest evidence, and next step. Full dependencies, history, lease details, and failure reasons belong in the detail view. People can scan quickly while agents can expand the facts through stable identities.
+Do not collapse three kinds of grouping into one. Lifecycle state says whether a Todo is open, blocked, deferred, or done. Work type says whether it advances, monitors, gates, or reminds. A lane is a grouping, candidate set, or scheduling path for a particular actor. “In development” and “awaiting review” can be domain display columns without becoming universal Kernel states. Supersession is recorded by the supersede operation and relationships such as superseded_by, not by inventing another generic state.
| Work type | Purpose | Key distinction |
|---|---|---|
advancement_task | Implementation, research, validation, documentation, or repair. | Must produce a verifiable result; it is not limited to code. |
continuous_monitor | Observe an external change by condition or cadence. | Stay quiet without material change; polling count is not delivery. |
user_gate | Wait for a decision that blocks related work. | The scope must be explicit; “wait for the user” is insufficient. |
user_action | Remind a person to do something. | The reminder neither grants authority nor blocks work automatically. |
blocker | Record a missing execution condition and recovery path. | A person may not be needed—for example, while a test environment recovers. |
The same “independent review” card can be visible but excluded for the development agent, yet claimable by the review agent. Work claimed by someone else may still appear as context, but the current agent cannot take it over merely because it is visible. claimed_by, excluded_agents, dependencies, capabilities, gates, and the current budget all affect execution eligibility.
Therefore, open does not mean runnable; high priority does not bypass a Gate; appearing on the board does not mean the current agent may execute. Quota and scheduler logic derive current routing from these facts. The returned contract distinguishes executable obligations from suggestions. Diagrams and the Planning Horizon help with understanding; neither is a second scheduler.
+Claims and leases: responsibility is not execution occupancy
+Claim: who owns the card
+A claim usually appears as a Todo’s claimed_by. It tells other agents that someone owns the work and lets state writes check the actor. It is soft ownership: it does not prove the process is alive or a Host is bound, and it is not a pass around authority checks.
Ordinary lifecycle operations must honor current owner and authority rules. Cross-owner completion, reassignment, or supersession requires explicit delegation already allowed by the contract. Calling an agent a “steward” or “coordinator” does not automatically grant permission to modify every Todo.
+Lease: which execution is currently valid
+When a Goal selects the corresponding hard-lease collaboration mode, a lease can also carry execution-instance identity, TTL, version, and write scope. Renewal must prove a valid holder and matching version. Expired, invalid, or stale versions cannot count as current execution authority. Supported operations also depend on the selected provider and completed migration stage.
+When reading a lease, TTL is its validity window, version identifies its current revision, and epoch can be understood as a generation of execution occupancy that separates old and new actors. Fencing is the pre-write check: an expired or ineligible actor cannot use an old identity to commit a protected write even if its process is still running.
+
Current quota does not consume hard leases automatically. Whether a lease is used depends on the actual Host and execution-path integration. A claim can exist without a hard lease; a valid lease can exist while a release Gate, missing capability, or budget boundary still prevents execution. A lease constrains only paths integrated with its fencing and cannot provide “exactly once” effects for every external system. Stopping the old executor and starting the new one still require the corresponding Runtime supervision and recovery.
+A common mistake is to read “replay succeeded” as “authority is still valid.” An idempotent replay returns the historical result of the original operation; it does not renew the lease. Read the current lease before continuing to write. Existing canonical lease renewal explicitly supports renewal for promoted local File and SQLite providers. That does not mean transfer, release, reclaim, and the full actor lifecycle have qualified for every provider.
+Gates and dependencies: wait precisely, and continue precisely
+A dependency answers whether a fact has become true. A Gate answers whether the relevant decision or authority exists. A test environment that has not recovered and an upstream artifact that has not arrived do not necessarily require human approval. A release that needs confirmation cannot substitute more monitor cycles for authority.
+A Gate must have scope. Use the corresponding lane scope when a decision blocks only one agent. Use a concrete Todo link or typed decision scope when it affects one action. Use an explicit global Gate only when the whole Goal truly pauses. A continuation binding such as goal-bound does not imply a global block.
The release Todo references the production decision. Integration validation and documentation can continue when they are independent, authorized, and otherwise eligible. Moving the release card to “ready” does not consume the Gate, and an ordinary user reply cannot be interpreted arbitrarily as release approval.
Dependency, successor, and supersede must also remain distinct. A dependency is a prerequisite. A successor identifies who continues the work; it does not automatically mean “wait until the previous item completes.” Supersede means a new route replaces an old one and must not disguise invalidated work as success. A wait condition may bind to Todo completion, a material Monitor change, or another supported event.
+Recovery rechecks current conditions: the revision may have changed, authority may have been revoked, and an artifact may have expired. See Decision Scope, the Todo Contract, and the task-graph projection.
+Evidence: make “done” a judgment that can be checked
+“Done” on a board must open into a reason. First separate three things: an Artifact is the deliverable, Evidence supports a judgment, and a Receipt records that an operation was accepted or observed. An exported file is an artifact; permission tests and sample inspection are evidence; a “release request submitted” receipt proves only that the request occurred.
+| Question | Example |
|---|---|
| What was validated? | Candidate revision A, its Todo, and this execution. |
| Which check was performed? | A negative permission-isolation test, large-volume integration test, independent review. |
| What is the result and boundary? | Record passed, failed, and untested separately, including applicable inputs and environment. |
| How can someone inspect and reproduce it? | An authorized artifact reference, run record, exact version, or digest. |
| What change would make it stale? | A change to code, input, dependency, or authority that affects the conclusion. |
“The summary contains a hash,” “the test command exited 0,” and “an agent sent a message” each prove only a limited fact. Whether evidence satisfies acceptance requires domain validation and, where needed, independent judgment. The control plane preserves identity, scope, result, and relationships; it does not invent correctness on behalf of a person or validator.
+Put concise, authorized references on the shared board. Keep raw logs, user data, and private documents in authorized storage. Possessing a reference is not reading the content; receiving material is not adopting it; being able to read evidence is not authority to act. The agent-scoped evidence ledger provides a bounded timeline and compressed frontiers from other agents—not a second task database.
+Shared authority state: let every participant know which facts count
+If two agents both read “unclaimed,” or one agent returns from another Host with stale state, sharing a table is not enough. The system must know who may commit, which version the write is based on, who loses a conflict, and how to recover when an operation committed but its response was lost.
+Shared authority state is the authoritative state and write boundary everyone agrees to follow. It does not require putting everything into one giant database. The corresponding Todo, claim, and lease aggregates have their own owners; Goal intent, request and response, and external effects retain their own transaction boundaries. Explicit relationships and receipts reconcile across boundaries instead of pretending one transaction encloses every system.
+
Shared facts, committed by version
+On supported canonical transaction paths, a commit carries an expected revision. Compare-and-swap (CAS) asks whether someone changed the state after it was read. The commit result binds the event to the original operation receipt. A competitor cannot overwrite a new owner merely because it also saw the stale card. A lost response is recovered through the identity of the original operation rather than by blindly executing it twice.
+Read local defaults, provider selection, and promotion separately
+LoopX retains both legacy paths and gradually migrated provider paths. Promotion formally moves a Goal’s authority source to a selected canonical provider. An unpromoted Goal still follows the existing Markdown or local-writer authority rules; a provider-first call without a selector chooses the File profile. Selecting a File, SQLite, or PostgreSQL provider neither promotes a Goal nor automatically grants cross-host write authority.
+File and SQLite have concrete transactions and real-backend validation. Full continuous-operation qualification, a default switch, and owner promotion for SQLite remain separate boundaries. PostgreSQL has provider and service integration contracts plus a test foundation; authentication, tenant isolation, network failure, and cross-host operation must qualify under the relevant profile. “An implementation exists” cannot be presented as “every deployment is ready.”
+After promotion, an empty read from the selected canonical provider means empty, and a failure must be reported explicitly. The system cannot silently fall back to legacy Markdown or a legacy lease file and keep writing. Markdown may remain as a readable projection; UI, cache, and rows synchronized to external boards remain projections too. For more detail, see Local Authority Provider Selection and the Shared Authority RFC.
+Put the objects together into one collaboration
+-
+
- Define the outcome. The owner submits the bulk-export Goal, acceptance, and release constraints. Work becomes identified Todos, with explicit responsibility boundaries between implementation and review. +
- Select and claim. A development agent reads the current eligible candidates and claims implementation. If the selected mode requires a lease, it also obtains valid execution occupancy. A successful claim does not remove the need to check environment, capability, and authority. +
- Execute and write back. Implementation produces a candidate revision and test evidence. Failures and partial success are recorded honestly. The end of a Turn does not complete a Todo automatically. +
- Take over and validate. A successor review binds the candidate identity and acceptance. The reviewer takes over through its own admission and claim path, reads the artifact, and reaches a conclusion. Registering a receiver, delivering a message, and actual takeover are three different facts. +
- Handle waits. Integration validation can continue while the release Gate constrains only matching work. If the revision changes, an old review does not qualify the new candidate; the relevant validation must be confirmed again. +
- Accept and return. Once agreed acceptance and required release authority are satisfied, deliver through the appropriate domain process and read back the result. If gaps remain, link an existing successor or replan. Return the completion conclusion to the original audience. +
This path shows how several capabilities cooperate. It does not imply a universal command that performs the whole collaboration in one step. Frontend, Lark, CLI, and real Runtime entry points, takeover, and result return must each be validated. A count of registered workers is not evidence of execution or acceptance.
+How to read a LoopX board in practice
+For routine inspection, this order is enough. Start with the Goal’s acceptance gaps, then inspect the current agent’s work lane. Open the selected Todo and confirm its owner, dependencies, and Gates. Inspect the lease when concurrent execution needs it. Finally expand evidence and the next step. When information is incomplete, follow stable identities into detail; do not infer “does not exist” from “is not displayed.”
+These are the query entry points for a connected Goal. Replace placeholders with real, registered identities. For source development, run uv run --extra test loopx … from the corresponding worktree; for an installed build, use loopx directly.
# Current goal and expandable work graph
+loopx --format json status --goal-id <goal-id> --include-task-graph
+
+# Work from the current agent's perspective; identity is not display order
+loopx --format json todo list --goal-id <goal-id> --role agent --agent-id <agent-id>
+
+# Current lease facts for one work item
+loopx --format json task-lease inspect --goal-id <goal-id> --todo-id <todo-id>
+
+# Bounded evidence timeline visible to the current agent
+loopx --format json evidence-log --goal-id <goal-id> --agent-id <agent-id> --thin --limit 20Write operations use lifecycle entry points exposed by the current Todo, Gate, claim or lease, and runtime contract—not by editing a display column or constructing status prose. Read current command help and the returned action contract to learn required parameters, whether an execution identity is needed, and whether work can continue.
+The CLI and local frontend expose operations and read models at different levels. Lark has corresponding messages, goal channels, and a Base board adapter, but that does not establish full equivalence across every field and action. The Lark Kanban adapter still identifies itself as a prototype contract: synchronization and triggers require configuration, and an external board does not create another task identity system.
+Advanced I: make state transitions executable contracts
+Once the basic objects exist, “in development → awaiting review” is more than moving a card. It must identify the delivered revision, evidence, review work, and subsequent modification boundary. The model proposes a next step; the control plane checks identity, preconditions, and relevant authority; then it records acceptance or rejection.
+LoopX organizes Todo completion, successor binding, and next-step updates as lifecycle operations; see Todo Next Action. Domain capabilities organize business stages such as development, review, and release. The Kernel need not hard-code every project’s business columns.
+Request submission, successful execution, state commit, and user-visible result remain distinct stages. At the end of an operation, the system should answer “what is now a shared fact, and how does the next participant take over?”—not merely append an activity row.
+Advanced II: give agents bounded, expandable decision context
+Sending the entire board and full history to a model can bury the current constraints. Returning only “do the next item” loses dependencies and alternate routes. A Planning Horizon provides nearby work, relationships, waits, acceptance gaps, and a small number of comparable options.
+LoopX’s Planning Horizon is a bounded read model. It must disclose coverage and truncation and allow expansion by identity. It must not quietly change authority through summary order or mistake a local view for global state.
+A reviewer needs: “Review revision A. Current tests pass, but large-volume evidence is missing. The developer is adding validation. Release is not authorized.” That is closer to the decision than a complete chat transcript. Suggestions remain suggestions; machine-enforced execution obligations must be explicit in the contract.
+Advanced III: reassess the Goal after a Todo completes
+A merged pull request may complete implementation without making bulk export usable to a user. When local work completes, link an explicit successor, create genuinely necessary work, or state why no successor is needed. Preserve supersession when direction changes.
+If the task chain is exhausted while acceptance remains unmet, replan. If acceptance is established, stop. LoopX’s replan settlement binds writeback to a specific completed identity or obligation. It does not count a task created only to close the process as progress.
+No-follow-up settles the current continuation question; it does not automatically accept the entire Goal. Adoption of a message, release of a lease, and marking a Todo done each prove a change only at their own layer.
+Advanced IV: preserve facts and boundaries through cross-layer recovery
+Runtime and Harness provide execution and sessions. The control plane maintains identity, state, and legal transitions. Domain capabilities and models organize routes and acceptance. The board presents the result to people and agents. Good interfaces let them cooperate without allowing one layer to take over another layer’s authority.
+If a remote action happened but the local response was lost, a “pending” state does not prove the action did not occur. Recover through existing idempotency identities, receipts, and result queries. When evidence is insufficient, preserve uncertainty. Lease expiry does not undo external actions that already happened, and retry is not universally safe.
+Shared authority can protect commits inside the boundary it owns. Workflows across code repositories, release systems, and messaging channels still need their own effect and reconciliation contracts. See From one-shot agents to long-horizon control for the complete layering and Effect Programs.
+How to tell whether the board actually improves collaboration
+-
+
- Two actors claim at once: can the system determine who succeeded and who must reread, instead of leaving both believing they may execute? +
- A stale actor returns: can an expired lease, version, or source be misused? Are external actions that lack fencing identified explicitly? +
- The reviewed revision changes: can old evidence be mistaken for validation of the new version? +
- Release awaits confirmation: does the Gate block release while independent, authorized validation continues? +
- A card completes or is superseded: can someone read back the artifact, remaining acceptance gaps, successor, and reason for the change? +
- The authority source is unavailable: can the system silently fall back to an old file and create two writers? +
- The board or history is truncated: can readers discover undisplayed work instead of incorrectly declaring the Goal complete? +
This is also how to read capability status: separate published foundation contracts, optional modes, operations validated for a particular provider, and product paths that still need end-to-end qualification. This article is pinned to a public revision. Command readback and qualification evidence for the deployed version determine what a deployment can do.
+A useful LoopX board should let a person and the next agent answer together: Where are we going? Who owns the work now? What can continue? What must wait? What is the evidence? How will the next step be validated? The core objects supply a shared language; long-running collaboration keeps it intact across sessions, interruptions, and changes in direction.
+Implementation and documentation are pinned to a96c9aa91. The four diagrams and the bulk-export scenario are synthetic explanations, not production screenshots or performance data. This article does not claim equivalent qualification across every Host, provider, and product entry point.