Design: Lane, Ask, and Role boundaries
Status: designed, mostly not built. Written after a direct code audit, not from memory of the docs -- several things below are corrections to what the docs currently claim, not just additions. Revised once already, same day, after the model grew from "fix a few confusing boundaries" to "the Lane is the one real primitive."
Superseded in part: the "Coordinator doesn't exist in RbacRole" finding below was true when written, and became the reason to actually retire "Maintainer" from the repo-level Role and rename it to Coordinator directly -- a real merge of the two names this doc found colliding, not just a clarification of which was which. RbacRole is now "owner" | "coordinator" | "contributor" | "viewer". The historical analysis below is kept as the record of how that confusion was actually found.
The Lane is the singular primitive; Ask, Ladder, repo, Policy, and Roles are its facets
Not five peer concepts that happen to relate to each other -- one thing, with five facets:
- An Ask -- specifically, the one that caused this Lane to exist. A Lane receives many Asks over its life (
claim_request,changeset_review,vote_request, and so on are all ordinary protocol traffic within a Lane); exactly one Ask is the creating one, and that relationship is 1:1 in both directions -- every Lane has exactly one creating Ask, every creating Ask produces exactly one Lane. - A Ladder -- its own state/knowledge record, 1:1 with the Lane, following the same origin-chain shape a Lane's own relationships already have: a work Lane's Ladder merges upward into its origin's, the same way the Lane itself traces back to its origin.
- A repo -- the backing store, de-emphasized in the UX on purpose. See Lanes and Ladders.
- A Policy -- inherited from the origin at fork time (see below), overridable per path the same way Policy already works.
- A set of Roles -- also inherited at fork time, with one addition (see below).
This resolves the question this page opened with under its old framing: a Lane doesn't merely have a repo and a Ladder, it is the primitive those are facets of. "1 Ask, 1 Lane, 1 Ladder, 1 repo" is really just "1 Lane," stated four different ways.
Policy and Roles inherit at fork time -- as a snapshot, not a live link
When a new Lane forks from an origin, it inherits the origin's Policy and Role grants as they stood at that moment -- with one addition: the actor creating the fork is granted Owner on the new Lane, on top of (not instead of) the inherited owners. The new Lane's owner set is the union of the origin's owners and the forking actor, not a reset.
This should follow the exact snapshot discipline already designed for agent-creation-chain trust inheritance -- inherited_trust(agent) = decay_factor × trust(created_by, at creation time) -- rather than inventing a second inheritance mechanism for the same shape of problem, per principle 5. Concretely: a later change to the origin's owners shouldn't retroactively alter every fork's owner set (the inheritance was a snapshot, not a subscription) -- except, by the same asymmetric-revocation logic trust-inheritance already settled, an upheld whistleblow against an inherited owner probably should cast doubt forward, the same way a compromised signing key casts doubt on signatures that were valid when made. Flagged here as the likely right answer, not yet fully decided -- tracked as its own issue below.
Creating a Lane, including an origin Lane, is one verb
The gap this closes: an origin Lane currently has no creating Ask at all, breaking the 1:1 relationship above for exactly the one case that matters most (a repo's own root). The fix is a single, unified verb:
zz lane create <name> <description> [--origin <lane-ref>] [--from <github-url>] [--policy ...] [--grant ...]
- No
--origin: creates a root/origin Lane -- a new, standalone backing repo, never completing, always open to new Asks for the life of the repo. This replaceszz repo createoutright. --origin <lane-ref>: forks from that Lane's backing repo to create the new Lane's own. This replaces the sharded claim path's implicit repo-creation (ensureShard) with an explicit, named operation.--from <github-url>: seeds the new Lane's history from an existing GitHub repo instead of from nothing -- ingest becomes a flavor of Lane creation, not a separate pipeline, consistent with principle 5.
Every one of these posts a real creating Ask carrying the name, description, and any non-default config (Policy overrides, Role grants) -- including the origin-Lane case. There's no longer a special, Ask-less bootstrap path.
This also makes concrete what was previously the separate, more abstract proposal to make the in-place-vs-sharded claim decision "a Policy question" -- --origin is that decision, made explicit at the moment of creation rather than implied by which CLI command happened to be used.
Shard and fork: implementation detail, not user vocabulary
In the UX -- CLI help text, web app copy, docs written for someone using the system rather than extending it -- there's only Lanes and the Lanes related to a Lane, by origin. "Shard" and "fork" stay, scoped deliberately to the moments actually explaining the git mechanics underneath (this page included, and --from/--origin as flag names are an acceptable, deliberately narrow exception, naming the git-level operation precisely for the one audience -- someone choosing how to create a Lane -- who needs to know it's happening). The relationship graph this produces is structurally isomorphic to a git DAG (a root, descendants) but that's a statement about shape, not rank: a Lane descended from another is a peer of its origin, the same different but equal argument already applied to identity, now applied to the project's own information architecture.
Origin Lanes vs. work Lanes: a real lifecycle distinction, entirely undesigned until now
An origin Lane -- what the code currently spells _repo -- never completes. A work Lane is different in kind: it exists for one Ask, has a real beginning and end, and needs an actual answer to "then what" -- dispose of it, keep it for auditability, or dispose of it after some retention window. LaneStatus already declares "merged" | "closed" | "vetoed" | "stopped" (engine/types.ts), but a full-repo check found zero call sites that ever set any of them -- the lifecycle is declared and entirely dead. A clean gap, nothing built yet to contradict.
The database model already has the right shape, on the wrong table
Confirmed directly: worker/migrations/0007_repo_shard_origin.sql already adds exactly the right column -- shard_of_slug TEXT NULL REFERENCES repos(slug), a single self-referencing nullable FK -- just on repos instead of on a unified lanes table. No join/mapping table exists or is needed: the relationship is a strict tree, one parent per node, and the existing tree-walking code (shardGroupedListHtml, the recursive shard-cleanup in webApp.ts) already walks that single pointer in application code rather than a recursive SQL query. The fix here is relocating this exact column onto lanes as origin_lane_id (nullable, NULL for an origin Lane), not inventing a new relationship model -- the schema already got this right once.
Renaming _repo to origin, and why that's three fixes, not one
The string "_repo" is doing three unrelated jobs today, confirmed directly in code, and the code already has its own comment flagging the collision (webApp.ts:1758): the root Lane's id (engine/lane.ts), the Ladder's root rung path (engine/ladder.ts's REPO_RUNG_PATH), and the key in a repo's Policy document governing changes to Policy itself (repo-policy.ts). Formalizing "origin Lane" terminology means only the first of these becomes origin. The other two are a different axis that happens to share a string with it today; conflating them further would be the opposite of the fix.
The role confusion, precisely located -- and a bigger question underneath it
Audited directly against repoMeta.ts's actual RbacRole type and every real enforcement call site, not against docs or memory. The role model itself isn't conceptually broken. Owner/Maintainer/Contributor/Viewer are four real, mostly-distinct repo-level roles, and "Coordinator" was never a fifth one -- it doesn't exist in the RbacRole type at all, and Core Concepts already correctly scopes it as Lane-only. The confusion traced to two narrow things:
A misleadingly-named constant. worker/src/webApp.ts's COORDINATOR_ONLY_REMOTE_TOOLS -- named for the Lane-level concept -- gates commit_changeset and ladder_write_rung on repoAtLeast(role, "maintainer"), the repo-level Role, with zero reference to Lane.coordinators. A reader has every reason to expect Lane-coordinator semantics and gets repo-Maintainer semantics instead.
A doc that didn't match its own demo. Protocol said "An Owner can invoke [STOP/DROP/ROLL] directly." The demo always used Lane-coordinator authority. Fixed directly in this pass: Lane coordinator is now stated as the normal authority, Owner as a universal override -- the same escape-hatch shape already reconciled with different but equal for Policy.
Confirmed thin but real, not broken: Contributor vs. Viewer differ only in read access to a private repo -- narrow, but a real distinction.
That was the state of the audit as first written. It doesn't survive contact with "the Lane is the singular primitive" above. If Policy and Roles are both facets of a Lane, and an origin Lane is just the Lane every other Lane in a repo traces back to, then "repo-level Role" was never really a separate axis from Lane-scoped roles -- it's the Role grants on the origin Lane specifically, wearing a different name. zz repo grant's own awkwardness once nested under lane (below) is the symptom; this is the actual diagnosis: the repo-level RbacRole type should very likely retire entirely, replaced by Lane-scoped role grants everywhere, with "repo-wide" access simply meaning a grant on the origin Lane. Owner's delete/transfer-ownership semantics map cleanly onto "terminate/transfer the origin Lane" -- the same "a repo is one long-lived Lane" framing this project already uses. This is bigger and more consequential than the two narrow fixes above, needs real verification against the full capability matrix the original audit produced before it's implemented, and is tracked as its own issue rather than folded into the smaller ones.
CLI verb surface, checked against what's actually registered today
Checked directly against cli/zz.ts's real command tree, not assumed:
zz repo create-- becomeszz lane create(above).zz repo clone <owner/repo> [dir]-- becomeszz lane checkout. "Checkout" never means "create a new thing" in git vocabulary, unlike "clone," which has picked up fork-ish connotations from GitHub culture; this keeps a clean split wherecreateis the only verb that ever produces a new Lane.zz repo grant-- pending the role-axis-collapse decision above; if it lands, this becomes a Lane-scoped grant with no separate repo concept at all.-- done 2026-10-19. Both retired;zz repo ask <owner/repo> <description>andzz repo asks <owner/repo>zz ask post(now defaulting its Lane argument to the origin Lane, and gaining--decompose) and a newzz ask listreplace them, working on any Lane rather than only the origin one. The one real, previously-invisible dependency this surfaced: the retired commands' own dedicated REST route lazily bootstrapped a brand-new repo's origin Lane on first post, which the genericask_posttool call didn't -- fixed at the server (handleApiCallToolself-heals on exactly that "no such lane" error) so every caller gets this, not just the CLI.zz repo policy show/set-- becomeszz lane policy show/set, since Policy is a Lane facet now, not a repo one.zz repo submit <owner/repo> <lane-id> <ask-id>-- becomeszz lane submit <lane-id> <ask-id>, dropping the redundantowner/repoargument now that a Lane id implies it.zz lane propose <repo> <name>-- overlaps with the new unifiedzz lane create; needs its own resolution (fold intocreate, or keep as a narrower convenience for proposing a work Lane inside an already-known repo) rather than assumed away here.zz repo delete-- becomes terminating the origin Lane specifically, a distinct, higher-stakes operation from ordinary work-Lane disposal/retention (already its own issue below).
Web app and TUI need to move in step with this, not after it
The TUI is reported to already be close to entirely Lane-native in its own vocabulary -- the lighter lift of the two. The web app still has real repo-centric surface (settings pages, the Roles panel, Policy panel) that needs to track whatever the role-axis-collapse decides, not drift from it. Tracked as its own issue so it doesn't get silently deferred past the CLI/engine work it depends on.
Fixed directly in this pass
Protocol §Incident response now says the Lane's coordinator holds the normal authority to invoke STOP/DROP/ROLL, with an Owner's universal override stated explicitly as an override, not the primary path.
Execution plan -- what's filed, and in what order
- issue 35 Disentangle
_repo's three overlapping meanings; formalize the Lane-identity sense asorigin. Foundational -- do first. - issue 41 Decide and implement the role-axis collapse: retire repo-level
RbacRole, move everything to Lane-scoped role grants, origin-Lane grants standing in for "repo-wide." The big one -- verify against the full capability matrix before implementing. Supersedes issue 36's narrower fix if it lands; issue 36 stays open as a fallback otherwise. - issue 36 Fix
COORDINATOR_ONLY_REMOTE_TOOLSnaming/enforcement -- narrower fallback if issue 41 doesn't land first. - issue 37 Unify Lane and repo creation under
zz lane create [--origin][--from], Ask-driven -- now the concrete resolution of this issue's original, more abstract scope. - issue 42 Policy/Role inheritance at fork time as a snapshot, reusing the trust-inheritance pattern -- including the asymmetric-revocation question.
- issue 38 Wire up real Lane lifecycle: actually set
merged/closed/vetoed/stopped. - issue 39 New Policy axis for completed work-Lane/shard retention -- depends on issue 38.
- issue 43 CLI verb cleanup:
retire-- done 2026-10-19, see above. Still open and genuinely blocked:zz repo ask/asks, addzz ask listzz repo clone→zz lane checkout,zz repo policy/submit→zz lane policy/submit, resolvingzz lane proposevs.create-- all three need a realzz lane create/Policy-as-a-Lane-facet model that doesn't exist yet (and isn't the same thing issue 37, as filed, turned out to be about -- see that issue's own correction). - issue 40 Remove "shard"/"fork" from user-facing language.
- issue 44 Update the web app and TUI once the above lands -- TUI lower-lift, already mostly Lane-native.
Placed on the work queue as the second step of the next development spike, after local concurrency isolation and before merge resolution -- merge resolution's own work happens inside Lanes, and building more protocol machinery on top of Lane semantics that are about to change is exactly the kind of avoidable rework principle 5 argues against.