Planning: dependencies, the map, and what is ready

An issue can wait for another issue. That one fact, kept as one row per edge in the forge's own tables, is the whole planning model: the map draws it, the ready list reads it, the crew's planner writes it, and nothing else remembers a plan.

The edge

#5 waits for #3 is a dependency. It lives in issue_dependency, both issues in the same repository, and it is refused when it would close a loop — a plan with a cycle has no first step. Anyone who can write the repository, or is on its crew, may link and unlink; a planner agent's whole job is to open issues and link them, so crew membership is enough here where it is not for assigning (which spends money) or merging (a person's call).

On the issue page, Depends on says _Waits for 2, 1 still open_ and _Holds up 3_, with each issue linked and a field to add one. The terminal's issue screen shows the same line, Waits for #12, #15 · Holds up #20, when there is any, and a click on a number opens that issue. There a writer presses w and types a number: a new one is linked, and one it already waits for asks a confirm, then is unlinked. A refusal reads in dependencyWords' sentences, as MCP wait_for says it. The page, the terminal and wait_for all go through linkIssue and unlinkIssue (src/actions/dependencies.ts). Over the API:

GET    /api/v1/repos/:owner/:name/issues/:n/dependencies   → { blockedBy, blocks }
POST   /api/v1/repos/:owner/:name/issues/:n/dependencies   { "blockedBy": m }
DELETE /api/v1/repos/:owner/:name/issues/:n/dependencies/:m
POST   /api/v1/repos/:owner/:name/issues/:n/dependencies/:m/confirm

A refused link says why: self, cycle, cross_repo, not_an_issue. Linking is an event (issue.blocked, issue.unblocked) like any other change, so hooks and the crew see it.

The map

/:owner/:name/map draws the repository's open issues, laid out by what waits for what. Closed issues are not drawn unless the page is asked for ?done=1 ("Show done" beside the counts; "Open only" returns). Ready now, Blocked on, the critical path, the marks, the counts and the pillar rows are still computed on the whole graph, so a closed blocker still frees what it held. The layout cache keys on the graph drawn, so each filter has its own. Each issue is a card one level below everything it is blocked by, so the top edge is what is ready now. Within a level, cards are ordered to keep the curves short and uncrossed: a barycenter pass sorts each level by where its blockers sit, then by where its dependents sit, and a transposition pass swaps neighbours wherever that draws fewer crossings. An edge that skips levels is routed down the gutters between cards, never under one. Issues that wait for nothing and hold nothing up stand apart below the chains, under a rule, so a backlog of loose items never crowds the plan. The longest chain of open issues runs in the accent, at the same weight as every other edge: the least work that still has to happen one thing after another.

What a card says. Its title on at most two lines, who is on it when someone is, and one word:

accent ring. Nothing on the map animates on its own: an animation inside a large inline SVG repaints the whole drawing every frame.

Later gate, it is filed under Later, or only deferred work needs it. The card, the data (deferredBecause) and the issue's own page say which, in the same words: "behind the Later gate", "filed under Later", or "only deferred work needs it: #12 One interface", naming the deferred limbs above it. A dashed, quiet card.

last spoke on it; a quiet warning tint. It is the planner's now (below).

Working outranks waiting, waiting outranks parked, parked outranks deferred, and the rest is what the graph says. Under the drawing, one line counts them.

Fit, pan, zoom. The drawing fits its container's width on load and never overflows the page sideways. Drag pans it; ⌘ or Ctrl and scroll (a trackpad pinch, or two fingers on a phone) zooms around the pointer; the _fit_ button puts it back. Every card is a link to its issue, so the map is read by keyboard too, and the view follows focus. The drawing is a live region: a card turns to _working_, a pull lands, or a new issue appears while the page is open, and the reader's pan and zoom survive the swap.

Beside the drawing, the three lists the crew and a person both read:

ones whose finishing frees the most, then the oldest.

counted through everything that transitively waits.

And two weeks of the repository's open count drawn as a line over issues closed per day drawn as bars. They share a chart and not an axis, because a level and a flow are different units: the line says whether the plan is converging, the bars say whether anything is moving.

The roadmap

/:owner/:name/map opens on the roadmap (#10303), ?view=graph is the drawing. How to read it and where else it is: docs/features/roadmap.md.

The same three lists are data at GET /api/v1/repos/:owner/:name/map, which is what an agent reads before it starts (issues and edges hold only open issues; ?done=1, or done: true on MCP map, brings the closed ones back; counts.done always says how many) and what a repository in autonomous mode reads to pick the next thing. Both carry where the crew is: an issue with an agent run in flight is marked _working_ on the drawing and listed under working in the data; every issue in the data carries its word, and counts sums them. parkedTwice lists each issue the crew handed to the planner — its number, title and every reason.

The global map

/map is every app on one page, one lane each. Each repository the viewer can see that has an open issue or a run in flight is a lane, headed by its name (a link to its own map), how it runs itself — _off_, _assisted_ or _autonomous_ — today's spend as a thin bar against the ceiling with the numbers beside it when it is not off, who is working (their avatars), and the same count line as the repository's map. The lane is the same drawing as the repository's map, drawn at the widest lane's width so one scale and one grid hold across every lane; nothing is ever drawn across lanes. A lane with nothing in flight and no card that says _ready_ is idle: it folds to its header, and opens on a click. The page is one live region, and a reader's folds, pans and zooms survive its swaps. Repositories with nothing to draw are left out; a forge with nothing to draw anywhere says so in one sentence. It is reached from the user menu and the command palette, and from the Apps card on either home. GET /api/v1/map is the same, one entry per repository, each the repository's map data plus autonomy, spentTodayUsd, week, inFlight, workers and idle.

Parked twice

An issue the crew parked twice since someone who may direct the crew last spoke on it is struck out: the clock holds it, but never for good (crew/retry.ts). It is startable again when its inputs change since its newest park (a comment, a dependency closed, its text or the direction issue edited by someone who may direct the crew; a restart is not a change) and otherwise once a day, the builder given every earlier reason; the Crew page lists each with a "Try again" button, and the terminal's Crew hand-overs screen has t (docs/features/crew-try-again.md). A reader's comment does not start the count again, and neither does the planner's. A park is the crew's own note, written in the name of someone who directs it or by one of the repository's agents; a comment that only reads like one strikes nothing. A struck-out issue is not dropped. The second park says every reason on the issue, in the one note, and hands it to the planner (crew/parks.ts):

planning run asks the planner once — with a full map, and even when the planner declined the direction and no person has spoken. Its task lists _Parked twice: #n_ with every reason.

split into its parts), replaced (a fresh issue, the old one closed as split into it with "replaced by #m"), or deferred (linked to wait for the Later gate — the open issue whose title starts _Later gate_, which the owner closes to let deferred work start — with the reasons in a comment). A planner closes an issue by exactly this grant, on an open issue the crew parked twice: split, only into open issues made since the hand-over, never the issue itself or the Later gate, so a closed or an old issue cannot stand in for a drop; and dropped, only when no person's ask stands in the issue: an agent wrote it, and it did not come from a split of a person's issue, however many splits ago (standsForPerson). What a person asked for is dropped by a person. Never done, never a pull, never a reopen, never on a mirror.

say over their own issue is a person's. An agent closes an issue by landing a pull for it or by the grant above, and reopens none — so the issue a planner opened to replace a person's ask is not the planner's to close, and the ask cannot be lost that way (#724).

whoever owns the app, with its reasons and a link to the issue; and under parkedTwice in the map's data and the MCP's map. A comment from the planner or a builder does not take it off. What does: it is closed, it waits for something open, someone takes it up (a run in flight, or an open pull that would close it), or a person says on it what to try.

Planning by the crew

An agent's brief says how: open issues each small enough for one run, link what waits for what, read the map. A planner that never builds — Atlas, on this forge — turns a direction into a map that way; a builder that finds a task too big for one run splits it into linked issues instead of leaving half of it. Either way the plan is where everyone can see it, and closing an issue is what frees the next.

Pillars and the Later gate

A direction can name what the work is for. Each such _pillar_ is an open umbrella issue whose title starts with its name — P0 Trust: … — and an issue serves the pillar whose umbrella waits for it; nothing else records it (src/core/pillars.ts). A title alone does not make one: the umbrella, the gate and the Later umbrella count only when a person who writes the repository opened them here — not an agent, not a reader, not an issue imported from an origin — so on a public repository a stranger's "P0 …" makes no pillar and their "Later gate: …" holds nothing. Work that serves no pillar is not dropped and is not ready either: it waits behind the _Later gate_, the open issue whose title starts Later gate:, opens with one sentence that says why it waits, and stands under the Later: … umbrella where the repository keeps one. The owner moves an item out by unlinking it from the gate, or opens them all by closing the gate.

A plan says which it is for every issue. The planner plans through one route, POST /api/v1/repos/:owner/:name/plan with { "issues": [...] } (rw scope; a crew member's run token may use it), which calls the same action as the MCP plan tool (openPlan): the same items, the same refusals, all or nothing. An item names its pillar, or is later: true with why; one that says neither is refused with no_pillar and nothing is opened, so the planner reads the refusal, names the pillar or defers the item, and posts again. The answer is { opened, ready, held, later, gate }. held lists each opened issue that is ready but would not start now, as { key, number, by, detail }: by is one of the map's hold names (HOLDS in src/crew/held.ts) and detail its sentence. The usual ones are hot_file (a file on the issue's Files: line is hot, or an admin holds it); an open pull cannot hold an issue opened a moment ago. The planner can rewrite what is held in the same run. A repository with no umbrella issues has no pillars, and plans as it always did.

An issue opened outside a plan. A builder that finds its task too big for one run opens smaller issues one at a time and links them. Such a split child serves its parent's pillar: when the parent serves one, the builder makes that umbrella wait for the child as well (POST …/issues/U/dependencies with {"blockedBy": child}). It does not choose a pillar of its own and is never deferred by the builder; where the parent serves none, the child serves none either. Only a plan names new purposes.

The umbrellas, the Later umbrella and the gate are the plan's own, not work. None of them is ever _ready_, so the crew never picks one and the map never lists one under _Ready now_; one with nothing open in front of it reads _parked_, "the plan's own: a person closes it, the crew never picks it". An agent does not close one, whatever access it holds, and a merged pull does not either, whatever its body says it closes: a person who writes the repository closes an umbrella when its pillar is done, and closing the gate opens everything behind it.

Membership is direct: an issue the umbrella itself waits for. Under two umbrellas an issue serves the first, and a pillar outranks _Later_, which is what waits behind the gate or stands under the Later umbrella. Umbrellas and the gate are the plan's furniture: one umbrella waiting for another is an order between pillars, not membership.

What a person sees (#610). core/pillars.ts is the one reader of all this; three surfaces show what it reads.

Later for deferred work — made the first time it is needed, and no other pillar's. actions/pillars.ts writes it where the edges change (a link or an unlink, a plan, a split, where each umbrella that waited for the whole now waits for its parts) and at boot for what was linked before. The label only says what the edges say: it is never read back, and one set by hand does not survive the next boot. That holds for a label the repository already had under a pillar's name: at boot it is taken off every issue that does not serve that pillar. A mirrored repository's labels are its origin's, so none is written there.

and _Later_ — a link to its issues, the list narrowed to its label — with what is open, ready and blocked, then _no pillar_ with the issues that serve none, each a link, since they are the ones to file. In the data every issue carries pillar (null for none), pillars is the same rows, and mergedByPillar is { days: 7, counts: [{ pillar, merged }] }: the pulls merged in the last 7 days, each counted under the pillar of the first issue it closes that serves one. Each pillar's count also carries askToLive: {medianHours, slowest: {number, hours}} (null, a dash on the page, when none merged has gone live): hours from that issue opening to the first production deploy whose commit contains the pull's merge, by git merge-base --is-ancestor, cached. The MCP's map and milestones answers carry it too, on each pillar's limb.

each app that has pillars: every pillar and its count, zero or not, each a link to its issues.

Milestones

How far each thing asked for is, read from the dependency tree (core/milestones.ts); nothing is stored. A _milestone_ is an issue that waits for others, and what is beneath it is everything it waits for, directly or through others. The plan's furniture is beneath nothing: one pillar's umbrella waiting for another is an order between pillars.

/:owner/:name/milestones is the plan as a handful of _limbs_ — the pillars and Later, or, in a repository with no pillars, the issues that wait for others and that nothing waits for. Each is one line with its weight: done of total, open beneath it, how many are building, pulls merged in the last 7 days, its last movement and, for whoever may see owner facts, what it cost. The work counted is what is open and what closed as done; dropped and split issues are neither.

/:owner/:name/milestones/:number is one milestone opened: who is building what, what is blocked and on what, what merged this week, and a plain estimate — the open issues at the pace of the last 7 days, or a sentence saying there is no pace to estimate from. Under it, issues closed per day over 14 UTC days as a sparkline and one line from the same numbers: on pace for <date> (today plus the estimate's days), no movement in 7 days, or done <date> (the day the last issue closed); a deferred milestone has no line. The terminal's milestone list shows the line for the limb under the cursor, and the MCP gives closedPerDay, paceDate and pace. What it waits for directly shows as limbs where a child brings a tree of its own, and as leaves where it brings none (one that only waits for its siblings is a leaf in an order). Leaves show only on the limb they are under, and each issue shows once: what is under _Building now_ or _Blocked_ is not listed again under _Issues_. Later's milestone counts what the map's Later row counts: what the Later umbrella waits for, and what waits behind the gate whether or not the umbrella waits for it.

A limb is flagged _a candidate to trim_ when it has open work, nothing landed in 7 days and it has been here that long, or when it has eight or more open issues and nobody building. Later is deferred on purpose and is never flagged.

It is one tap away: each pillar in the map's _By pillar_ and in the board's 7-day line opens its milestone, the map names the page, and the issue page of anything that waits for others says _see how far it is_. The same numbers are data at GET /api/v1/repos/:owner/:name/milestones (the limbs as { items, next_cursor }, with limit and cursor) and …/milestones/:number, and in the MCP's milestones: building is the count on a limb and on a milestone alike, and buildingNow lists who is on what. An agent's name and the spend are the owner's to see: a reader gets "the crew" and no cost.

Trimming at a limb

Whoever administers the repository acts on a whole limb from its milestone, not on each leaf (#733). Each action is one fleet operation (docs/FLEET.md): a preview that lists every row it writes and every issue it takes along, nothing written until it is confirmed, a receipt, and one undo.

limb first: out from under its pillar, under Later, behind the Later gate — one row for each, so nothing is put off that the preview did not show. (On a plan where every issue is linked under its pillar, moving the limb alone would leave its leaves ready.) What other work outside the limb still waits for stays pickable and is listed as staying; an umbrella's wait is membership, not need. Anything linked beneath a deferred issue afterwards follows by the graph's own rule — an open issue that only deferred work waits for is deferred too, and is never ready. An issue nothing waits for at all is not touched by the rule. Each deferred issue reads _deferred_ wherever it is shown, with why: on the map, in its data and the MCP's map, on its own page, and on the milestone.

back under the pillar named, or under none; an issue of the limb that was not filed for later is left as it is.

the limb included, as dropped, with the reason said on each. What other work outside the limb also waits for is not the limb's to close.

siblings — the pillars and Later at the top, a milestone's limbs under it. The place is stored per group of siblings (limb_place), kept across a restart, and is the order the limbs are listed in; a limb never placed follows the placed ones, by number. The preview shows the new order and how the top of the ready list changes. Once a person has set an order in a repository, the crew's ready order follows it: an issue beneath a higher limb comes before one beneath a lower limb (beneath two limbs, the higher), after them come issues beneath no limb, and within a limb the order is the old one — what it frees, then age. Until then nothing about the ready order changes. It is one fleet row, the verb place; undo puts the place back. Through the API and the MCP limb tool (action raise or lower, under when the limb sits in several places), dry-run by default.

larger pieces. The preview lists every open issue the planner will be given. Pressing it writes the hand-over (limb_replan, with the issues it was given) and owes the planner one pass, even with a full map, even after it declined the direction, and without waiting out the hour since its last pass. Its task names the limb and lists the issues. Until the planner has answered — a planning run begun after the hand-over has ended — the limb reads _With the planner_ on its milestone and the crew picks nothing beneath it (the with_planner hold). The planner may close an issue beneath it only as split into open issues made since the hand-over, as for a twice-parked issue; it may not drop one, and the hand-over grants nothing outside the limb. A person may take it back until a planning run has begun. Afterwards the milestone lists which old issue closed into which. Not a fleet operation: it writes no issue row, so there is no receipt to undo; taking it back is the undo. In the terminal, p on the limbs screen (Milestones in a repository) previews what the planner is given and hands the limb over on confirm; the row then reads _with the planner_, and p takes it back while allowed. Through the API and the MCP limb tool as action replan or takeback, dry-run by default (the dry run is the list of issues).

An umbrella or the gate is the plan's own and is not filed. A leaf beneath a limb that is not deferred cannot be deferred alone: defer the limb. A candidate to trim offers Defer first.

The same is POST /api/v1/repos/:owner/:name/milestones/:number/limb { "action": "defer" | "resume" | "close" | "raise" | "lower" | "replan" | "takeback", "reason"?, "pillar"?, "under"?, "dryRun"? } and the MCP's limb, both a dry run unless dryRun is false. Applying and undoing take an admin token of a person who administers the repository; an agent may look and never apply.

Watching a milestone

A person who is signed in presses Watch on a milestone, once (#732); pressing it again stops. A watch is theirs alone: one row per person and issue (core/watches.ts), no event, nobody else told. What it says is read from the plan each time, as that person:

there is something new: how far it is and what merged since they last opened it from the feed, or began to watch. The item is renamed as the milestone moves, so it is one item however many pulls merge, and a dismissal holds only until the next one does. Muting the app does not mute it.

through the notify URL (crew/notify.ts). Landed means its issue closed as done, or the last open issue beneath it closed. Progress never pages, and neither does a milestone that was dropped or split: the feed says that it will not land as written.

A watch on a repository the person can no longer read says nothing, in the feed or on the phone. An agent does not watch. The same is PUT and DELETE /api/v1/repos/:owner/:name/milestones/:number/watch with a write token, watching on the milestone's read, and the MCP's watch. On the terminal's Milestones screen, w on a row watches or stops; a watched row reads _watching_, and an agent is told only a person watches.

A repository on its own

A repository has one setting for how much the crew does without being asked, under Settings → Autonomy:

check failed. The default.

allows, the top of the ready list is assigned to a builder. Every green pull waits for a person's look.

a passing deploy lands as the person who turned autonomy on — with their review and check requirements still enforced inside the merge. Nothing about a green pull reaches a person: first, a pull that no longer merges because main moved under it sends its agent one run (conflict, naming the files) to merge main into the branch, one waiting at a time, up to the same limit a failing check has; then the green head goes to the crew's _reviewer_ (review run: the diff, the preview, the pictures the forge took), whose approval lands it and whose change request goes back to the builder as feedback; a crew with no reviewer lands it. With two reviewers, a change to sign-in, tokens, secrets, the sandbox or the HTTP edge goes to the one whose brief says it reads for security, and every other change to the other (crew/review.ts). Every green pull an agent wrote is sent this way in any repository with a reviewer, autonomous or not; a review run is ok when it posted a verdict, since a reviewer pushes nothing. A review that does not come back — the run ends without a verdict, or is still out after 20 minutes — is sent once more; after the second, or an hour green with no verdict however the runs went, the review has lapsed and the pull lands on green with a note saying so. A missing reviewer never holds a pull silently. An agent's verdict stands only while the agent is a reviewer on the crew, and the reviewer gets two rounds of changes on a pull — a round is a head it asked changes on; past them its request is advice, and the third request hands the pull to a person in one card summarising the three reviews (not parked, not closed; a person's approval lands it). A builder's run that answers a change request without pushing parks the pull. A review run never resumes an earlier session, and the same verdict sent twice on one head is one. A red check goes back to its builder with the failing output until it is green; when the same red comes back after a rework the pull stays open and the asks say so, and a new head or a person's word starts it again. A pull whose branch could not be brought up to date is _parked_ — closed with the reason, its issue put back on the map unassigned with the same note — and the crew moves on. An approved pull is finished before anything starts: a slot freed goes first to an approved pull that no longer merges, then to a pull with changes requested, then to a new issue, and one whose two updates ended without a push is handed to the person who turned autonomy on — assigned to them, not closed (crew/finishing.ts; the tick line says finishing="queued Q, in flight F, skipped S: <why>×k", or finishing="0 candidates of N open"; each skipped pull is logged once per reason as finishing: skip pull=N why="…", and every open pull that is not a candidate as finishing: drop pull=N why="…"; it reads every open pull, not the newest fifty). The planner's next pass splits or rewrites a parked issue, and one parked twice is handed to the planner (below). The planner keeps a standing reserve of startable work — two issues per builder slot, never fewer than three — and is asked whenever fewer than that can start, not only when the map runs dry. It is told the direction is never finished: when what it names is built, it proposes the next increment, and a pass that leaves the reserve short says why on the direction. The reviewer gets two rounds of changes on a pull; the third hands the pull to a person. The only pause is the day's ceiling. A person steers by editing the direction and the map; the crew does the rest. When nothing is ready and nothing is in flight, the map has run dry: the planner is given the direction.

Everything it does, it does as that person, through the same actions they would take by hand — an assignment, a merge — so every run and every landing is credited and bounded exactly as theirs would be.

The crew's roles. An agent declares its roles in its own config, beside its model and brief (Settings → Crew → the agent; roles on /api/v1/agents and the agent MCP tool): any of planner, builder, reviewer, one or more. A repository's team is three lists, Planners, Builders and Reviewers, each picking only from agents that declare the role, with how many may work at once beside it; a repository narrows what an agent declares and never widens it, and there is no default to builder. /migrate and a new app offer builders only, and a dispatch never hands an agent a job outside its seat: an issue assigned to a planner gets one comment saying so. Each crew member then holds one of its roles on the repository: a _builder_ takes what is ready; a _planner_ turns the direction into a map; a _reviewer_ is for the look-back. Which builder takes an issue is one fixed-choice function: the issue's own assignee when it is a builder here, else the builder with the least in flight, then by name — the place a faster or wiser decider plugs in later.

The direction is one or two sentences on the settings page. When the map runs dry the forge opens an issue titled _Direction: …_ that carries it, assigns the planner, and the planner's brief says the rest: open issues each small enough for one run, link what waits for what, assign nobody, push nothing. The direction issue stays open, is never picked as work. A pass that did not end well — a decline a person answered, a failure — is not followed by another for twenty minutes; one that ended well has no floor. Nor is it asked again with nothing new: when nobody but the planner has spoken on the direction since its last pass began, and no issue has been opened by anyone else or closed since that pass ended, the clock skips it and records one guard decision by rule. A busy crew counts the startable issues before it plans; full slots alone are not a short reserve. Every tick line says reserve=startable/target (src/crew/reserve.ts).

What counts as done and as taken. A pull that says _Closes #12_ closes #12 when it lands, as the person who landed it; that is what frees the map, on any repository, autonomous or not. An open pull that closes an issue means the issue is proposed, neither ready nor done, and the tick leaves it alone. An issue a builder ran on and left without a pull is stalled: running it again blind is the loop autonomy refuses, so the next tick parks it in the crew's name — a note with whose run stalled it and the run's last summary, the assignee cleared — and another builder may pick it; the one that stalled it leaves it for the hour unless a person says what to try. A second stall strikes it out and hands it to the planner with both reasons. The tick line counts them as unstuck=N (src/crew/stalls.ts). A person's comment on it is a feedback run like any other. On every tick, green pulls that have not landed — a check that passed before autonomy was on — land, so nothing green waits on chance.

What holds it. The ceiling is dollars of agent spend per UTC day; at the ceiling the crew stops picking until midnight, and nothing in flight is cut. Slots are the builders' runs at once — the WIP limit — and a repository never starts more than that, whatever the forge-wide concurrency allows. A reviewer's pass over a pull and a planner's run on the direction take no slot: they refill the map rather than work it, and they never keep a builder from picking the next issue. The number a page shows is that same count, so what the page says and what the loop gates on are one thing. A failing check on an agent's pull goes back to the agent as ever, and after the same bounded number of tries the crew stops and waits for a person: autonomy re-queues nothing a person must decide. The map page says how it stands: _Autonomous · $12.40 of $40 today · 1 of 2 slots_, and why it is paused when it is.

Relieving a hot file

A planner may write a Relieves: <path> line in an issue only for a change whose purpose is to cut what other pulls must touch in that file (a split, an extraction), and the path must also be on its Files: line. Such an issue is not held by that file being hot (three paths at most), but only one at a time per file: while an open pull or a run serves another issue that relieves the path, the second waits (waits: <path> is already being relieved by #N), and an admin's pin on the file still holds it. The line is read from any issue body and the author is not checked, on purpose: the exemption lifts only the hot-file count, never the other holds, it admits at most three paths that the issue also lists under Files:, and one relieving build per file bounds what a stray Relieves: can pile up.

Holding a pull

A person who writes the repository can say "not this one yet" about any open pull, with one line that says why (src/core/holds.ts, src/actions/holds.ts). While the hold stands, no rule touches the pull: it is not sent to the crew's reviewer, not landed on green or on an approval, not brought up to date by the crew, and not parked (parking would close it and hand its issue back to be built again). A person's own merge still works; the hold is on the rules, not on people. One word that ships many changes at once is the exception: a batch from the asks leaves a held pull where it is and says who holds it and why, since whoever sent the batch may never have seen the hold. They ship it from its own page, or release it first. An agent cannot hold or release, on the crew or not, and neither can a reader.

Releasing starts the review clock again: review is owed from when the head went green or from when the pull was last let go, whichever is later, so a pull held past the hour and then released goes to the reviewer like any newly green one and is never landed as lapsed.

The hold shows on the change page and the pull's own page with who and why, and on the map the issue the pull answers says _held_. It is set and lifted from the change page, with PUT and DELETE /api/v1/repos/:owner/:name/pulls/:number/hold, or with the MCP hold tool, which plans unless told dryRun: false. A held pull asks nothing of the person who holds it.

The decider

Some of what the forge does is a decision, not a generation: which builder takes a sentence, how big it is, what kind of ask it is; whether a red check is the change's fault or the environment's; which option on a card a careful owner would pick. Every one has the same shape — a state, a set of questions each with fixed choices, a probability per choice out — and every one has a rule that answers it today. crew/decide.ts is that shape, and a decider is anything that answers it better.

With TYPESAFE_API_KEY set, TypeSafe's Jev is the decider: a System One model that answers fixed-choice questions with calibrated probabilities in well under a second and never generates text. The forge asks it through POST /v1/systemone with the state as a record of named facts and each question as a choice with criteria — the options, and what each means. TYPESAFE_MODEL picks a model (jev-latest by default); TYPESAFE_URL points elsewhere for a stand-in.

The rule is never gone. A decider that is absent, slow past its budget, errors, or names a choice outside the options leaves the rule's answer in place, and by says which answered. Nothing a decider says is acted on outside the choices the forge wrote down, which is what makes its answers safe to act on without a person.

Where it decides today:

small, large) and kind (bug, feature, question, chore). Asked when a sentence is told in the studio and when a repository on its own picks from the map. An issue already assigned to a builder keeps its builder; the decider is not asked.

on its own has more than one ready issue, the decider chooses among the first six with the direction in hand. The rule takes the top of the ready list, the critical path.

lands by rule, once its base merges cleanly and it does not cross the wall (docs/CONTRACT.md). Nobody is asked; the ledger keeps the landing as a ship by the rule, once per head, so the week's numbers add up. A pull lands once: the merge reads the pull's row, not the caller's copy, and a squash whose tree is the base's own commits nothing — the pull closes as merged into the commit that carried it, and main does not move (#2017).

judgeFailedCheck): a failed check gets another automatic run by rule, up to the limit. The decider reads the failure, the log's tail and the count and answers both at once — whether another try is worth its money, and whether the change, the environment or the base branch is what failed. The cause is settled before anything is parked: an environmental failure runs the check again (below) whatever the verdict, so a flaky runner never throws a change away. Otherwise _stop_ waits for a person as a stopped ask, and the parked reason says which of the two it was.

The ledger. Each of these is written to the decision table (core/decisions.ts): what the decider saw, what it answered and with what probability, who answered (the decider or the rule), and later what came of it — a landed pull, a retry's next check green or red, a picked issue shipped. GET /api/v1/repos/:owner/:name/decisions lists it with the week summed per kind. It is the value function's raw material: whether the decider beats the rule is a query, not an opinion.

above — from the tail of the check's log, whether the change, the environment or the base branch failed. At 70% or better the environment's fault runs the check again, once per head commit, instead of the agent reworking a change that is fine or the pull being parked for someone else's bad luck. A second red on the same commit is real: the pull parks, saying the environment.

Every answer a decider gives is a log line — decided by=typesafe ms=270 [email protected] [email protected] … — so what it said and how long it took are always in the forge's log.

Closing takes a reason

PATCH …/issues/:n { "state": "closed", "reason": "done"|"dropped"|"split", "into": [m, …] }. No reason means done. Done frees what waited. Dropped or split closes the issue but holds its dependents as _parked_, the map saying why ("#4 was dropped"), until a writer relinks them or confirms the edge (POST …/dependencies/:m/confirm, the page's "Still holds"); the crew may not confirm its own plan. Split also moves the parent's blocked-by edges to the issues named in into (a child that would make a loop is skipped), and the parent waits for nothing. Reopening clears the reason. Closes that predate reasons count as done.

Plans need a nod

A repository setting, plansNeedNod (PATCH /api/v1/repos/:owner/:name, admin only, never an agent), off by default: on, the planner's work waits for a nod and is not opened until then. On, POST …/plan and the MCP plan tool run every check as ever (no_pillar, loops, unknown keys) and then store one proposal — title, why, the ordered issues with their blockedBy — answering proposed with its id (HTTP 202). No issue is opened. Off, the plan opens its linked issues all or none. A person's nod opens a stored proposal: approve in src/actions/proposals.ts, from the inbox card or the MCP asks_proposal.

A business, as a map (#439)

Atlas turns a business described in words into apps, adapters and what waits for what, dry-run first and opened through openPlan once: the API (POST …/atlas) and the terminal's Atlas plan. How to use it: docs/features/atlas-plan.md.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs