Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs(atlas): resolve review — make the pages agree with themselves (F…
…IX-1437)

Review found places where the re-derived prose was correct but a figure,
tag, or cited path beside it still taught the superseded version. Replaced
the stale text rather than annotating it.

conductor.html
- §6 figure: the cancelled FIX-1247 fence still read as proposed-but-filed
  in all three representations (aria-label, visible SVG text, figcaption).
  All three now match the prose at L788/L862: the fence was cancelled,
  nothing refuses the call, nothing on the tracker will. Visible text moves
  from f-accent to f-gone to match the cancelled vocabulary.
- §6 figure: "THE FRAMEWORK VERB IS SPECCED, NOT BUILT" contradicted both
  its own aria-label and §8; board.unparkAndDrain ships in orchestration.
- §10: the open thread is where a host's MaterializeAgentFn implementation
  lives, asked with the first real role block — matching thread 11.
- §11: dropped the instruction to treat fence claims elsewhere on the page
  as lapsed; there is nothing left to distrust.
- §12 thread 20: maxEnqueuedTasks bounds a single up-front fan-out burst,
  checked at creation, per task-caps.ts — not a steady-state bound.
- Run-anatomy: "Provision workspace" is plain `exists`; the module left the
  lab, as the row's own description already said.
- Cited paths: inbox.ts and run-record.ts are in packages/harness-manager,
  not labs/conductor. Every remaining labs/conductor/src/ citation verified
  against the directory.

roadmap.html
- Relay door row now lists both SessionTarget forms that reach an existing
  session, agreeing with the dispatch row above it.
- Layer 1 packages row points at each package.json instead of pinning
  version numbers that rot.

Docs-only; no published-package consumer is affected, so no changeset.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt
  • Loading branch information
claude committed Sep 18, 2026
commit 4baa6bcc00a5b6590095df97c298fde547c5609a
20 changes: 10 additions & 10 deletions docs/atlas/conductor.html
Original file line number Diff line number Diff line change
Expand Up @@ -842,7 +842,7 @@ <h3>Where a gate lives</h3>
<thead><tr><th>Step</th><th>Status</th><th>What it does</th></tr></thead>
<tbody>
<tr><td>Resolve inputs</td><td><span class="tag t-real">exists &middot; lab</span></td><td>Read the durable task &#8212; issue and phase &#8212; the previous attempt's feedback, and any answered questions, and fold them into the prompt (<code>labs/conductor/src/implement.ts</code>). This is the whole of "what does this run need to know". The approved spec belongs to a phase the lab does not run yet</td></tr>
<tr><td>Provision workspace</td><td><span class="tag t-real">exists &middot; lab</span></td><td><code>git worktree add</code> on the issue-phase's own branch, at a path derived from the durable task and never read back from a record; idempotent per issue-phase, and one live attempt per tree, resolved by waiting rather than failing. The module left the lab with the manager: it is <code>packages/harness-manager/src/workspace.ts</code>, with the git-worktree internals behind <code>@flow-state-dev/harness-manager/checkout</code> and the construction-time guards (<code>assertDistinctRepository</code>, <code>assertBaseRefExists</code>, <code>assertCheckoutRootUsable</code>) exported for a host to run at its own door (section 11)</td></tr>
<tr><td>Provision workspace</td><td><span class="tag t-real">exists</span></td><td><code>git worktree add</code> on the issue-phase's own branch, at a path derived from the durable task and never read back from a record; idempotent per issue-phase, and one live attempt per tree, resolved by waiting rather than failing. The module left the lab with the manager: it is <code>packages/harness-manager/src/workspace.ts</code>, with the git-worktree internals behind <code>@flow-state-dev/harness-manager/checkout</code> and the construction-time guards (<code>assertDistinctRepository</code>, <code>assertBaseRefExists</code>, <code>assertCheckoutRootUsable</code>) exported for a host to run at its own door (section 11)</td></tr>
<tr><td>Build prompt</td><td><span class="tag t-real">exists &middot; lab</span></td><td>Phase logic (section 7) turns resolved inputs into one string; the lab's manager takes a prompt builder as one of its three values</td></tr>
<tr><td>Start the run</td><td><span class="tag t-real">exists &middot; lab</span></td><td>The board seat is <code>dispatcher({ type: "task", target: assignee, session: "per-task" })</code>, so the drain hands the claimed row off and the run enters the manager in a child session keyed on the task id (<code>labs/conductor/src/flow.ts</code>). The seed is gone with it: nothing routes on <code>metadata.topic</code> any more, and it is a readable label on the row</td></tr>
<tr><td>Record the run</td><td><span class="tag t-real">exists &middot; lab</span></td><td>A <code>runs/**</code> row, user-scoped, keyed <code>&lt;epic&gt;/&lt;issue&gt;/&lt;phase&gt;</code>: checkout, branch, outcome and reason, the harness session as a copy, cost, child session, request id. The only handle a person has on a live run &#8212; and not the resume store (section 6)</td></tr>
Expand All @@ -863,14 +863,14 @@ <h3>Where a gate lives</h3>

<figure>
<div class="fig-body">
<svg viewBox="0 0 940 300" role="img" aria-label="Two placements for a wait. On the left, a gate as a parked task row: the request ends and the row stays, park-exit has shipped and the status is spelled parked, an answer unblocks the row with an input, a verb the framework ships as board.unparkAndDrain and the lab as answer, a new request picks the task back up, and the board is the durable state, so the epic waits. On the right, a pause inside a detached run: the parent returns the instant the child spawns, with the board row in progress and termination reason handed-off; the child calls suspend, the child pauses and nothing else does, a proposed fence to make that call an error is filed but not built, and the parent request no longer exists, producing a silent stall that looks like work. Therefore a question must travel as data, not as a pause.">
<svg viewBox="0 0 940 300" role="img" aria-label="Two placements for a wait. On the left, a gate as a parked task row: the request ends and the row stays, park-exit has shipped and the status is spelled parked, an answer unblocks the row with an input, a verb the framework ships as board.unparkAndDrain and the lab as answer, a new request picks the task back up, and the board is the durable state, so the epic waits. On the right, a pause inside a detached run: the parent returns the instant the child spawns, with the board row in progress and termination reason handed-off; the child calls suspend, the child pauses and nothing else does, a fence to make that call an error was filed and then cancelled, so nothing refuses it and nothing on the tracker will, and the parent request no longer exists, producing a silent stall that looks like work. Therefore a question must travel as data, not as a pause.">
<rect class="n-grp" x="16" y="26" width="446" height="212" rx="5"/>
<text class="t-lbl f-code" x="34" y="48">THE EPIC WAITS</text>
<text class="t-b f-human" x="34" y="72">A gate as a parked task row</text>
<text class="t-s" x="34" y="100">the request ends; the row stays</text>
<text class="t-xs" x="34" y="118">EXISTS &middot; PARK-EXIT SHIPPED &middot; RENAME LANDED</text>
<text class="t-s" x="34" y="142">an answer unblocks the row with an input</text>
<text class="t-xs" x="34" y="160">LAB SHIPS answer &middot; THE FRAMEWORK VERB IS SPECCED, NOT BUILT</text>
<text class="t-xs" x="34" y="160">LAB SHIPS answer &middot; FRAMEWORK SHIPS board.unparkAndDrain</text>
<text class="t-s" x="34" y="184">a new request picks the task back up</text>
<text class="t-b f-code" x="34" y="214">the board is the durable state</text>

Expand All @@ -881,14 +881,14 @@ <h3>Where a gate lives</h3>
<text class="t-xs" x="496" y="118">ROW in_progress &middot; terminationReason: "handed-off"</text>
<text class="t-s" x="496" y="142">child calls ctx.suspend(&#8230;)</text>
<text class="t-xs" x="496" y="158">THE CHILD PAUSES. YOU ARE NEVER TOLD</text>
<text class="t-xs f-accent" x="496" y="172">PROPOSED &#8212; A FENCE TO MAKE THIS AN ERROR</text>
<text class="t-xs f-gone" x="496" y="172">CANCELLED &#8212; NOTHING WILL MAKE THIS AN ERROR</text>
<text class="t-s" x="496" y="194">the parent request no longer exists</text>
<text class="t-b f-gone" x="496" y="214">a silent stall that looks like work</text>

<text class="t-lbl" x="470" y="272" text-anchor="middle">SO A QUESTION TRAVELS AS DATA, NOT AS A PAUSE</text>
</svg>
</div>
<figcaption><b>Two ways to wait, and a spawned run only has one of them.</b> All three gates of section 3 park a row: the request ends, the board holds the state, an answer starts a new one. Suspend is the main session's own mechanism &#8212; and today nothing refuses it inside a run, which is what the filed, unbuilt fence is for. The pause it prevents is not a missing feature; it is what "detached" means. So a question travels as data either way, and that is a subsystem with three faces: a place questions land, a thing that watches each run, and a channel back in.</figcaption>
<figcaption><b>Two ways to wait, and a spawned run only has one of them.</b> All three gates of section 3 park a row: the request ends, the board holds the state, an answer starts a new one. Suspend is the main session's own mechanism &#8212; and nothing refuses it inside a run, permanently: the fence that would have was cancelled, and nothing on the tracker will build one. The pause it prevents is not a missing feature; it is what "detached" means. So a question travels as data either way, and that is a subsystem with three faces: a place questions land, a thing that watches each run, and a channel back in.</figcaption>
</figure>

<div class="note">
Expand Down Expand Up @@ -952,7 +952,7 @@ <h3>Out &#8212; the inbox resource</h3>

<p><strong>The board partitions by epic; the inbox does not.</strong> A board is a claim pool, and one collection id is one pool &#8212; the claim predicate tests status and deps only, so two epics sharing an id claim each other's rows (section 4) <span class="tag t-real">exists &middot; lab</span>. An inbox is not a pool: nothing claims a row. The reason is who reads it, not key uniqueness &#8212; the lab's inbox says so, and rejects the uniqueness argument this page once made: the key is attempt-keyed from a board's counter, so two epics driving one issue-phase can both produce attempt 1, and what exempts the inbox is that its reader is a person. A key two boards write whose reader is a job needs the board's discriminator; a key whose reader is a person does not. An unfiltered <code>list()</code> spanning every epic is the product rather than a defect &#8212; it is your inbox, and everything waiting on you sits in one place.</p>

<pre class="code"><i>// EXISTS &middot; LAB &#8212; labs/conductor/src/inbox.ts, as shipped. Narrower than this page proposed.</i>
<pre class="code"><i>// EXISTS &#8212; packages/harness-manager/src/inbox.ts, as shipped. Narrower than this page proposed.</i>
export const inboxCollection = <em>defineResourceCollection</em>({
pattern: "inbox/**", <i>// inbox/&lt;issue&gt;/&lt;phase&gt;/&lt;attempt&gt;/&lt;fingerprint&gt; &#8212; no epic segment, a lock</i>
scope: "user", <i>// one set, shared by the session that answers and every run</i>
Expand Down Expand Up @@ -1373,7 +1373,7 @@ <h3>Continuity as a field on the task, not as session state</h3>

<p>The <code>runs/**</code> row carries a copy of the id &#8212; the lab's does &#8212; because it is what a person reads when they want to know what a run did. A copy is bookkeeping. The task is the mechanism, and the two should not be confused &#8212; a design that reads continuity out of the run row has put the load on the wrong record.</p>

<pre class="code"><i>// EXISTS &middot; LAB &#8212; labs/conductor/src/run-record.ts, as shipped. This page proposed</i>
<pre class="code"><i>// EXISTS &#8212; packages/harness-manager/src/run-record.ts, as shipped. This page proposed</i>
<i>// scope: "session" + sharedToLineage: true; the lab measured that and reversed it.</i>
export const runRecordCollection = <em>defineResourceCollection</em>({
pattern: "runs/**", <i>// ONE ROW PER ISSUE-PHASE, KEYED &lt;epic&gt;/&lt;issue&gt;/&lt;phase&gt;</i>
Expand Down Expand Up @@ -1725,7 +1725,7 @@ <h3>Per board</h3>
<div class="note">
<span class="lbl">Workforce is the product. Conductor is the old-run name</span>
<p>Supersedes the older &#8220;harness to drive / layer to choose / stay separate tracks&#8221; note. Workforce is the Layer&nbsp;2 product. The product name Conductor is retired. DevForce and Pentest Lab are sibling Labs on that product &#8212; neither hosted. One harness-manager stack &#8212; <code>@flow-state-dev/harness-manager</code>. Do not grow a Conductor-only path beside Workforce. Lock and retired-name claims: <a href="workforce.html#conductor">Workforce atlas &#167;16</a>. Demo nouns: <a href="workforce.html#lab">&#167;03</a>.</p>
<p>What remains open on this page is mechanical, not product: where <code>materializeAgent</code> lives (thread 11). That is implementer, not a sibling-ship fork.</p>
<p>What remains open on this page is mechanical, not product: if a role block needs an agent materialized, somebody writes the <code>MaterializeAgentFn</code>, and where <em>that</em> implementation lives is the question to ask with the first real role block in front of us (thread 11). That is implementer, not a sibling-ship fork.</p>
</div>
</section>

Expand Down Expand Up @@ -1849,7 +1849,7 @@ <h3>What has landed, and what is left</h3>
<li><strong>The harness manager</strong> (LAB-140). Its first generation drove one real issue end to end through the join &#8212; board claim, provision, start the run, read the outcome, decide &#8212; and is done. It has since moved onto the slice: the board seat is a task dispatcher and the manager is the flow's task entry. The second generation is the production shape, and three quarters of it has landed: LAB-152 put the harness contract in a neutral home, LAB-153 added a second harness, and LAB-154 took the manager out of <code>labs/</code> &#8212; all three <strong>done</strong>. LAB-141, which chooses the harness per task and carries the Proof, is the one left in backlog.</li>
<li><strong>Workspaces</strong> (FIX-150). <strong>Done</strong>, across PRs #1497 to #1511 &#8212; the package, the shell tool and the coding-agent path, and the overlap check across both. The provisioning module has <em>not</em> moved onto it, and it is no longer the lab's: it left <code>labs/</code> with the manager and is now <code>packages/harness-manager/src/workspace.ts</code>, whose package depends on <code>core</code> and <code>orchestration</code> and not on <code>@flow-state-dev/workspace</code>. So the seam is open at a new address rather than closed.</li>
<li><strong>The board's park mode</strong> (FIX-1234, then FIX-1244). Two issues, not one, both under the honest-task-substrate epic (FIX-980) and <em>related</em> to Relay rather than inside it &#8212; where the dispatch-protocol design counts the park as Relay's own issue 5. <strong>FIX-1234 has merged</strong>: a parked task now releases its launching request. <strong>FIX-1244 has merged</strong> (#1571) &#8212; unblocking that row with an input, so the answer arrives as a new request &#8212; and a parked row outside the lab now has something that wakes it. The rename to <code>parked</code> is FIX-1245, and it has merged (#1513). None of the three ever depended on the send verb, and the slice did not touch them.</li>
<li><strong>The fence on <code>ctx.suspend</code> inside a run</strong> (FIX-1247). <strong>Cancelled</strong>, not backlog &#8212; which changes what sections 4 and 6 are waiting for. Nothing refuses the call today, so a run that suspends parks its own request while the row still reads as work in progress and nobody upstream is told (section 6), and on the current tracker <em>nothing is filed that will change that</em>. The wrong mechanism stays reachable and fails quietly; treat &#8220;a fence is decided and filed&#8221; elsewhere on this page as lapsed until something re-files it.</li>
<li><strong>The fence on <code>ctx.suspend</code> inside a run</strong> (FIX-1247). <strong>Cancelled</strong>, not backlog &#8212; which changes what sections 4 and 6 are waiting for. Nothing refuses the call today, so a run that suspends parks its own request while the row still reads as work in progress and nobody upstream is told (section 6), and on the current tracker <em>nothing is filed that will change that</em>. The wrong mechanism stays reachable and fails quietly.</li>
</ol>

<div class="note">
Expand Down Expand Up @@ -2132,7 +2132,7 @@ <h5>19 &middot; Does a parked row hold its lease or release it</h5>

<div class="tension">
<h5>20 &middot; Max-N of one phase at a time is not expressible</h5>
<p>Three limits bound how much runs at once and they are easy to conflate: the board's <code>concurrency</code> is a worker pool <strong>across the whole board</strong>, <code>maxEnqueuedTasks</code> bounds how many rows may sit enqueued at once (<code>packages/orchestration/src/task-board/index.ts</code> &#8212; this thread previously called it <code>maxPending</code>, which is not a board option and never was), and entry arbitration bounds competing dispatches <strong>on one key</strong>. None of them says &#8220;at most two <code>implement</code> runs&#8221;. Setting the board pool to two caps every assignee together; arbitration is a mutex per key, so max-1 falls out of a constant key with <code>queue</code> and max-2 needs a counting semaphore nothing has.</p>
<p>Three limits bound how much runs at once and they are easy to conflate: the board's <code>concurrency</code> is a worker pool <strong>across the whole board</strong>, <code>maxEnqueuedTasks</code> bounds a single up-front fan-out burst &#8212; checked at creation against the resulting <code>pending</code> count, so it refreshes as tasks drain (<code>packages/orchestration/src/tasks/collection/task-caps.ts</code> &#8212; this thread previously called it <code>maxPending</code>, which is not a board option and never was), and entry arbitration bounds competing dispatches <strong>on one key</strong>. None of them says &#8220;at most two <code>implement</code> runs&#8221;. Setting the board pool to two caps every assignee together; arbitration is a mutex per key, so max-1 falls out of a constant key with <code>queue</code> and max-2 needs a counting semaphore nothing has.</p>
<p>Folded in: <code>notBefore</code> on a task row. Without it, &#8220;wake me later and confirm it happened&#8221; has nowhere to live &#8212; the deferred half is an outbox row, and the confirmed half is a board row, and nothing joins them.</p>
<span class="ask">Worth knowing before anything leans on it: a spec that assumes per-phase max-N is proposing a counting semaphore, not using one. Whether that is worth building depends on whether the board pool is a good enough approximation, and for one epic at a time it probably is.</span>
</div>
Expand Down
Loading
Loading