Skip to content

docs(atlas): roadmap.html and conductor.html, re-derived against the shipped code (FIX-1437) - #1886

Merged
jhoffner merged 4 commits into
mainfrom
fix/FIX-1437-atlas-staleness
Sep 18, 2026
Merged

jhoffner merged 4 commits into
mainfrom
fix/FIX-1437-atlas-staleness

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 18, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

The atlas sits at authority level 2 — above best practices. Twice now a stale atlas page has been trusted over the code: on FIX-1368 a wrong stamp shaped a decision that had to be reversed, and on FIX-1358 a tree taught slots that had shipped as proposed. Those two pages were corrected. roadmap.html and conductor.html were never checked, and both were carrying the same rot.

Most of it traces to one event nobody propagated: FIX-1344 deleted the Agent factory (defineAgent, createAgentRegistry, materializeAgent, agentBlock). Two pages still taught it as the shipped surface, in five places between them — including a whole open thread whose question was where materializeAgent should live.

What this does

Corrects the false claims on the two pages and leaves what is accurate. No framing is rewritten.

roadmap.html

Claim Reality
Workforce is defineAgent · registry · materializeAgent (two figures + §06) Removed by FIX-1344. It is hireWorkforce over WORKER.md, defineAgentWorkerFlow, the loader/codegen subpaths and the channel floor
"Version 0.0.0" core/engine/client/react 0.1.2, contracts 0.1.1, orchestration/workforce 0.2.1
"Only the { id } form sends to a session that already exists" { from: true } does too — the reply direction
"exists, thin" 6,501 lines of source

conductor.html

Claim Reality
§04 the harness manager is labs/conductor/src/manager.ts, "not a framework block" LAB-154 moved it to packages/harness-manager; the harness is a slot. Both halves of the claim reversed
§05 provisioning is labs/conductor/src/workspace.ts packages/harness-manager/src/workspace.ts. It still has not moved onto @flow-state-dev/workspace — that part held, at a new address
§01 examples/guides/research-team is the surface's only caller It imports nothing from workforce now
§01 kitchen-sink "uses it in zero source files" Four
§01 agents.md states "There's no cross-flow assignment" That sentence is gone; the page was rewritten. Lapsed, not settled
§11 LAB-152 / 153 / 154 "in progress" All three Done
§11 FIX-1247 (the ctx.suspend fence) "Backlog" Cancelled — so §04 and §06 were waiting on something nothing will deliver
§12 thread 20 maxPending bounds pending rows Not a board option; it is maxEnqueuedTasks
§12 thread 13 askPolicy/model/gate "already live" in the phase table PhaseSpec carries phase, buildPrompt, isDone, validate and none of those three

How the set was derived

Not from the two pages the ticket named. Two throwaway checkers ran over all four atlas pages, each derived from the concept rather than from instances already in hand, so they reach wordings nobody has written yet:

  1. every repo path cited inside <code> must resolve on disk;
  2. every identifier cited inside <code> must be findable under packages|labs|apps|examples.

Both were proved red before any green was trusted — an injected impossible value is reported, and run 1 found five real misses on first pass. The five remaining misses after this change are all deliberate absence claims (the page asserting a thing does not exist), which is the correct end state, not a suppression.

$ node cited-paths.mjs docs/atlas/*.html          # before
MISSING  conductor.html:775  labs/conductor/src/manager.ts
MISSING  conductor.html:844  labs/conductor/src/workspace.ts
MISSING  roadmap.html:496    packages/relay          # ← page says "there is still no packages/relay" — correct
MISSING  workforce.html:2557 packages/relay          # ← same
MISSING  workforce.html:2724 packages/workforce/src/define-agent.ts
57 cited paths, 5 missing

$ node cited-symbols.mjs docs/atlas/{conductor,roadmap}.html --selftest
NOT IN CODE  conductor.html:2067  resolveAgentPersona
NOT IN CODE  conductor.html:2087  askPolicy
NOT IN CODE  conductor.html:2136  maxPending
NOT IN CODE  conductor.html:2137  notBefore
NOT IN CODE  conductor.html:0     thisSymbolCannotExistAnywhere   # ← self-test fires

Every correction then had a second check behind it at a cited file:line — packages/workforce/CHANGELOG.md and the test asserting the shipped kind imports none of the removed symbols, packages/harness-manager/src/index.ts, packages/core/src/types/dispatch.ts:246, packages/engine/src/context/create-request-host.ts:388, packages/orchestration/src/task-board/index.ts:410, packages/harness-manager/src/manager.ts:158. Status claims were re-read off Linear, not remembered.

node scripts/check-isolation-coordinate.mjs passes, as do validate-no-nul-bytes and validate-spec-folder.

What's asked of you

Nothing blocking. Two judgement calls worth a look, and one thing this ticket could not close by itself.

1. FIX-1247 is cancelled, and three sections were written as though it were coming. The ctx.suspend fence is not merely unbuilt — nothing on the tracker will build it, so a run that suspends parks its own request while its row reads in_progress and nobody upstream is told, permanently. I recorded that as the standing state rather than as a pending fix. If it was cancelled because the parked row made it moot, the page now says so honestly. If it was cancelled by accident, this is the change that surfaces it.

2. Thread 11 is marked resolved-by-deletion, not resolved-by-choice. Its fork was "adopt the workforce wrapper, or move the piece down into orchestration". Neither happened: the piece was deleted and the injection seam (MaterializeAgentFn) kept. I wrote that as the outcome the leaning was reaching for, arrived at by subtraction, and moved the open question to who writes the implementation. That is a reading of intent, and it is the one edit here that is interpretation rather than fact.

Parts worth reviewing closely

  • The §12 thread 11 rewrite — the largest block changed, and the only place I replaced argument rather than a fact. Four paragraphs of source-layering analysis went away because the source they analysed went away. Check I kept what survived (the orchestration symbols, the core-resident persona types) and did not quietly retire a live question.
  • §11's "mostly done" tags. I re-read LAB-140's set off Linear rather than off the page. LAB-151 is In Review, which I left as "in review" — it was already right, and that is the kind of row a sweep breaks by touching.
  • The one claim I kept that looks stale and isn't. "The provisioning module has not moved onto @flow-state-dev/workspace" reads like the rot next to it. It is still true: packages/harness-manager depends on core and orchestration only. Only the address was wrong.
  • What I did not touch. The three-jobs framing (docs/atlas/README.md says Strategy owns that rewrite), and the masthead vintage dates — a date is not a false claim about code, and bumping them would imply a revision that did not happen. I updated only §11's explicit "checked against the tracker" line, which is a freshness claim I actually re-earned.

Found, not folded in

  • FIX-1441 (filed) — workforce.html §17 and framework.html:663 carry the same removed-factory rot, plus a packages/workforce/src/define-agent.ts citation to a file that does not exist and a "397 lines" count against 6,501. Fenced out of this ticket: FIX-1358 and FIX-1420 are in flight on both pages.
  • FIX-1439 — no overlap. The phrase "context and tools only" appears on neither of these two pages. Checked, not assumed.
  • FIX-1358, item 3 — not closed, and it got worse. The tree-teach-check.mjs on the never-merged spec/FIX-1358 branch is still the regex version: it looks for path.join(teamDir, …), FIX-1389 renamed that to team.dir, and it now reports five false FAILs blaming the atlas for slots the shipped readers demonstrably walk. Anyone acting on its output would delete five correct rows and call it an honesty fix — a sharper failure than the green-looking under-report already on record. Its --plant control does not catch it, because planting a slot in the atlas never exercises the reader half. I did not push to a spec branch that is in review; the reproduction and the ask are a comment on FIX-1358.

Closes FIX-1437.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt


Generated by Claude Code

RetriggerConfidence Score: 4/5

The PR appears safe to merge after two non-blocking documentation corrections clarify ownership and enqueue-limit semantics.

Fix All in CursorFindings

  1. P2 Stale lab status ▶
  2. P2 Enqueue limit overstated ▶

Summary

This PR re-derives the Conductor and roadmap atlas pages against the shipped workforce, harness-manager, dispatch, and task-board surfaces.

  • Replaces references to the removed Agent factory with the current workforce seat and loader APIs.
  • Updates harness-manager locations, package boundaries, and implementation status.
  • Corrects package versions, dispatch targets, phase fields, task-board option names, and tracker statuses.
  • Two documentation details remain inaccurate: a stale lab status and an overstated enqueue-limit invariant.

Reviews (1) · Last reviewed commit: "docs(atlas): re-derive roadmap.html and ..."

…d code (FIX-1437)

The atlas sits at authority level 2, and twice a stale page has won an
argument against the code. workforce.html §06 and framework.html's
isolation card were corrected under FIX-1358 / FIX-1420; the two sibling
pages were never checked. They were carrying the same rot.

Derived by two concept-level checkers run over all four atlas pages, each
proved red against an injected bad value before any green was trusted:
every repo path cited inside <code> must resolve, and every identifier
cited inside <code> must be findable in packages|labs|apps|examples. The
checkers are throwaway; the patterns come from the concept ("a citation
names a file", "a citation names a symbol"), not from instances already
in hand, so they reach wordings nobody has written yet.

roadmap.html
- The workforce package surface. FIX-1344 removed defineAgent,
  createAgentRegistry, materializeAgent and agentBlock; the page still
  taught them in two figures and the §06 inventory. hireWorkforce /
  WORKER.md / channels is what ships.
- "Version 0.0.0" — core/engine/client/react are 0.1.2, contracts 0.1.1,
  orchestration/workforce 0.2.1.
- "Only the { id } form sends to a session that already exists" —
  { from: true } does too (SessionTarget, core/src/types/dispatch.ts;
  engine/src/context/create-request-host.ts:388).

conductor.html
- The harness manager left the lab. LAB-154 moved it to
  packages/harness-manager; §04 still cited labs/conductor/src/manager.ts
  and called it "not a framework block", and §05 cited
  labs/conductor/src/workspace.ts. Neither file exists.
- §01's "agent surface is thin" note surveyed a factory that is gone, and
  claimed research-team was its only caller and kitchen-sink used the
  package in zero source files. research-team no longer imports it at
  all; kitchen-sink imports it in four files. The agents.md sentence it
  quoted is no longer on that page.
- §11 tracker status: LAB-152, LAB-153 and LAB-154 are Done, not in
  progress. FIX-1247 (the ctx.suspend fence) is Cancelled, not backlog —
  so sections 4 and 6 are waiting for something nothing will deliver.
- §12 thread 11 rested entirely on the removed factory; thread 20 named
  maxPending, which is not a board option (it is maxEnqueuedTasks);
  thread 13 said askPolicy/model/gate "already live" in the phase table
  when PhaseSpec carries none of them.

Left alone deliberately: the three-jobs framing (Strategy owns that
rewrite), workforce.html and framework.html (FIX-1358 / FIX-1420 in
flight — their share of this rot is filed as FIX-1441), and the
"context and tools only" phrase, which neither page carries (FIX-1439).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt
@vercel

vercel Bot commented Sep 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 18, 2026 6:29pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 18, 2026 6:29pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 18, 2026 6:29pm UTC

Request Review

@linear-code

linear-code Bot commented Sep 18, 2026

Copy link
Copy Markdown

FIX-1437

@jhoffner
jhoffner marked this pull request as ready for review September 18, 2026 18:06
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 18, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-18T18:09:50.073419Z 698019f Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify / review (FIX-1437)

Verdict: The re-derive-against-code direction is right, but this pass is incomplete and the edit style adds complexity (meta-changelog prose, duplicated FIX-1344 / FIX-1247 blocks) instead of subtracting stale text. I’m requesting one more sweep before merge—not a rethink of the whole atlas model.

What landed well

  • Harness-manager move (packages/harness-manager, workspace seam) matches the tree.
  • FIX-1247 cancelled is correctly reflected in §4/§6 prose and §11 table (good).
  • Thread 11 resolution (factory deleted, hireWorkforce + injected MaterializeAgentFn) is the right outcome.
  • maxEnqueuedTasks correction in thread 20 and the honest PhaseSpec vs §10 policy table note in thread 13.
  • Roadmap dispatch row: { from: true } / SessionTarget is the right inventory depth.

Incomplete staleness (same class of bug this PR fixes)

These still teach FIX-1247 as filed / a fence coming, while body copy says cancelled:

Location What still says “fence filed / proposed”
§6 figure ~L866 SVG aria-label: “proposed fence … filed but not built”
§6 figure ~L884 Visible label: PROPOSED — A FENCE TO MAKE THIS AN ERROR
§6 figcaption ~L891 “filed, unbuilt fence”

Also §10 note ~L1728 still says open work is “where materializeAgent lives (thread 11)” while thread 11 in this PR marks that fork resolved. That’s an internal contradiction introduced by partial updates.

Simpler fix than §11’s meta-instruction (“treat ‘fence is filed’ elsewhere as lapsed”): grep the file for fence, FIX-1247, PROPOSED, materializeAgent lives and replace or delete—don’t annotate that other paragraphs are wrong.

Roadmap consistency

In the same §06 table you correctly document { id } and { from: true } on the Task board / dispatch row, but the Relay door row (unchanged in spirit) still says only { id } reaches an existing session. Align that row (or point it at the dispatch row) so the inventory doesn’t disagree with itself.

Approach: did we go too far?

For a staleness PR, accretion is expensive:

  • §1 “agent surface” note and thread 11 read like audit essays (“this paragraph used to…”, “leaning recorded…”) on top of 2k-line HTML. Cleaner pattern: one short current-state paragraph + link to workforce.html / CHANGELOG for FIX-1344; delete the old survey text instead of narrating it.
  • FIX-1344 + kitchen-sink file lists appear three times (§1, thread 11, roadmap workforce row). One canonical inventory row; elsewhere a single sentence + link.
  • Pinned package versions in roadmap.html (0.1.2, 0.2.1, “as of this edit”) will rot on the next release—worse than the old 0.0.0 placeholder. Prefer “pre-1.0, not lockstep—read package.json” unless you add a generated snippet in CI.

Alternative I’d consider for follow-up (not blocking if you finish this sweep): machine-checkable claims (paths/exports exist)—the direction in #1884 / check-isolation-coordinate.mjs—so atlas edits are smaller and CI catches drift. No need to migrate off HTML for that.

Scope note

#1884 still tracks workforce.html / framework.html teaching the deleted Agent factory. This PR is correctly scoped to conductor + roadmap; worth either calling that out in the PR description or a tiny follow-up so readers don’t assume atlas is globally fresh.

Happy to approve after the §6 figure + figcaption + §10 note + roadmap Relay row are brought in line with the prose you already updated.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread docs/atlas/conductor.html
<p>The shape is right and the machinery is unfinished, so read every role claim above as a design on a young surface rather than as assembly of a working one. <code>Agent</code> (<code>packages/core/src/types/agent.ts</code>) has <strong>no <code>resources</code> field and no notion of scope</strong> &#8212; resources reach an agent only through <code>usesCapabilities</code>. <code>createWorkforceCapability</code> is a stub: a <code>// TODO</code> returning a bare capability. <code>usesSkills</code> is marked RESERVED and nothing resolves it, and <code>contextMode</code> documents that only <code>"inline"</code> is honored.</p>
<p>And <strong>almost nothing exercises it</strong>. Exactly one place does: <code>examples/guides/research-team</code> staffs a skill seat through <code>defineAgent</code> + <code>createAgentRegistry</code> + <code>materializeAgent</code>, and has a test &#8212; with an inline persona, session scope and a single flow, which is none of the three things this design leans on. <code>agentBlock</code> and <code>definePersona</code> are used nowhere outside the workforce package. <code>apps/kitchen-sink</code> declares <code>@flow-state-dev/workforce</code> as a dependency and uses it in zero source files, and no integration test touches it. There is no existing example of an org-scoped agent, of an agent carrying resources, or of one agent used across two flows.</p>
<p>Code and docs also disagree on precisely the point this design leans on. <code>apps/docs/docs/orchestration/agents.md</code> states <em>&#8220;There&#8217;s no cross-flow assignment.&#8221;</em> A probe built two flows off one agent and it compiled &#8212; which is a green build, not a green runtime. Recorded here as an unresolved contradiction, not as evidence either way.</p>
<p><strong>The factory this paragraph used to survey is gone, and that is the update.</strong> FIX-1344 removed <code>defineAgent</code>, <code>createAgentRegistry</code>, <code>materializeAgent</code>, <code>agentBlock</code> and <code>resolveAgentPersona</code> from <code>@flow-state-dev/workforce</code> (<code>packages/workforce/CHANGELOG.md</code>), and a test now asserts the shipped worker kind imports none of them (<code>packages/workforce/test/agent-worker-flow.test.ts</code>). <code>materializeAgent</code> survives only as an <em>injected function type</em> a host writes and passes to <code>createSkillsLibrary</code> for the <code>agent-ref</code> path (<code>MaterializeAgentFn</code>, <code>packages/core/src/types/agent.ts</code>; <code>packages/orchestration/src/skills/worker-materializer.ts</code>). No package in this repo implements one. So a role block reaching for an agent factory has nothing to reach for &#8212; which is a cleaner starting point than the young surface this note described, not a worse one.</p>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify: This note is now ~4 paragraphs of meta (“used to survey”, “reading this note carried”, “docs contradiction this note recorded”). For staleness work, consider replacing the old note wholesale with one paragraph: current workforce surface (hireWorkforce, stub capability, what’s still missing for org-scoped roles) + link to workforce.html / FIX-1344 in CHANGELOG. Same facts, half the words, no archaeology.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not acting on this one in this pass, and I want to be explicit that it's a scope call rather than a disagreement.

The diagnosis is fair — that note is written in audit-essay voice ("used to survey", "reading this note carried") and a reference page is not a changelog of its own edits. Where that voice was actively teaching the wrong thing I replaced it, which is what the rest of this pass did.

The reason I stopped short here: this note doesn't contradict anything. The stale content — the factory survey — is already deleted, and the facts that remain are accurate (verified: FIX-1344 removed defineAgent, createAgentRegistry, materializeAgent, agentBlock, resolveAgentPersona; MaterializeAgentFn survives as an injected type in packages/core/src/types/agent.ts; no package in this repo implements one). What's left is an explanation of a deletion, which is a concision judgment, not a staleness defect. Collapsing four paragraphs to one on a page whose author deliberately keeps derivation visible is an editorial decision I'd rather not make unilaterally inside a review round on a staleness issue — the risk is quietly dropping context someone chose to keep.

Flagging it for the page's owner as a real question rather than closing it: is the accretion voice in these notes worth a dedicated editorial pass? If yes, this thread and the §12 one below are the two places to start, and it should be its own change so the diff is reviewable as prose rather than mixed into fact corrections.


Generated by Claude Code

Comment thread docs/atlas/conductor.html
<p><code>ctx.suspend(options)</code> durably pauses a flow pending external human action: request status becomes <code>"suspended"</code>, a <code>SuspensionRecord</code> persists the whole context (<code>suspensionId, requestId, flowKind, actionName, sessionId, userId, reason, message, data, resumeSchema, render, allow, status, blockInstanceId, stepIndex</code>), and an HTTP resume route re-enters the action with <strong>completed steps replayed from the durable log rather than re-executed</strong>. <code>reason: "human_approval"</code> defaults <code>allow</code> to <code>["approve","reject"]</code>; <code>"human_input"</code> to <code>["submit"]</code>. It needs <code>durable: true</code> on the action and on the runtime. Four working shapes live in <code>apps/kitchen-sink/flows/chat-agent/</code>: <code>requestApproval</code>, <code>askQuestion</code>, <code>collectForm</code>, <code>chooseOption</code>.</p>

<p>All of that belongs to the <strong>main session</strong>, and it stays exactly as described. It is not the mechanism for anything a spawned run is involved in &#8212; and today nothing stops one reaching for it anyway. A run that calls <code>ctx.suspend</code> gets a suspension: its request parks, the row reads as a job still going, and nobody upstream is told. A fence making the call an error inside a run is decided and filed. <span class="tag t-prop">proposed</span> It is not built.</p>
<p>All of that belongs to the <strong>main session</strong>, and it stays exactly as described. It is not the mechanism for anything a spawned run is involved in &#8212; and today nothing stops one reaching for it anyway. A run that calls <code>ctx.suspend</code> gets a suspension: its request parks, the row reads as a job still going, and nobody upstream is told. A fence making the call an error inside a run was filed as FIX-1247 and has since been <strong>cancelled</strong>. <span class="tag t-gone">cancelled</span> It is not built, and nothing on the tracker will build it.</p>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good update here. The same fact still needs to propagate to §6’s figure (SVG aria-label ~L866, visible “PROPOSED — A FENCE” label ~L884, and figcaption ~L891). Right now a reader (or screen reader) gets cancelled in prose and “filed but not built” in the diagram—that’s the failure mode this issue is about.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 4baa6bcc0. All three representations now say what the prose at L788/L862 says — cancelled, nothing refuses the call, nothing on the tracker will:

  • aria-label (L866): "a fence to make that call an error was filed and then cancelled, so nothing refuses it and nothing on the tracker will"
  • visible SVG text (L884): CANCELLED — NOTHING WILL MAKE THIS AN ERROR, moved from f-accent to f-gone so the colour carries the same status as the t-gone tag in the prose
  • figcaption (L891): "nothing refuses it inside a run, permanently: the fence that would have was cancelled, and nothing on the tracker will build one"

Your framing was the useful part — the screen-reader path is a separate string, so fixing only the visible label would have left that reader with the superseded status.

While in this figure I fixed a second disagreement in the same class that wasn't flagged: the left panel's L878 read THE FRAMEWORK VERB IS SPECCED, NOT BUILT, which contradicted both its own aria-label ("a verb the framework ships as board.unparkAndDrain") and §8's exists tag. unparkAndDrain ships — packages/orchestration/src/task-board/, with tests. It now reads FRAMEWORK SHIPS board.unparkAndDrain.


Generated by Claude Code

Comment thread docs/atlas/conductor.html Outdated
<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). Backlog. 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). The fence makes it an error.</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>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instruction to “treat ‘a fence is decided and filed’ elsewhere as lapsed” is a smell that those elsewhere places weren’t updated. Prefer fixing §6 figure/figcaption (and §10’s materializeAgent / thread 11 line) over documenting lag in §11.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right on both counts, and both are fixed in 4baa6bcc0.

The instruction is deleted — L1852 now ends "The wrong mechanism stays reachable and fails quietly." Once §6's figure agrees with the prose there is nothing left on the page to treat as lapsed, so the sentence was documenting a lag that no longer exists.

§10's line is rewritten too. It said the open question was "where materializeAgent lives (thread 11)", which contradicted thread 11's own resolution in the same file. It now reads: if a role block needs an agent materialized, somebody writes the MaterializeAgentFn, and where that implementation lives is the question to ask with the first real role block in front of us.

You called the instruction a smell rather than a defect, which was the correct read — it pointed at two other places that hadn't been updated, and both were.


Generated by Claude Code

Comment thread docs/atlas/conductor.html
<p>Still <strong>unresolved</strong>, and the leaning has moved. It was toward building on workforce, on the argument that &#8220;different roles within a team&#8221; is precisely what workforce was reaching for and a second materializer would be duplicate surface. The evidence now points instead at <strong>moving the agent-as-block piece down into orchestration</strong>, rather than taking a dependency on a wrapper for one function. Neither is locked.</p>
<span class="ask">Not a decision to make now. It is one to make with the first real role block in front of us, because the layer only becomes obvious once something needs it. What to confirm then is the cheap outcome the evidence now favours &#8212; one function moving down into orchestration, and neither package adopted at all.</span>
<p><strong>Product fork closed, and the mechanical half has closed too &#8212; by deletion.</strong> Workforce is the product; the name Conductor is retired. DevForce and Pentest Lab are sibling Labs on Workforce, not sibling ships. See <a href="workforce.html#conductor">Workforce atlas &#167;16</a>.</p>
<p>This thread used to ask where <code>materializeAgent</code> should live, and surveyed a wrapper &#8212; <code>agentBlock</code> over <code>materializeAgent</code> over <code>createAgentRegistry</code>, with <code>defineAgent</code> beside them. <strong>None of that ships any more.</strong> FIX-1344 removed <code>defineAgent</code>, <code>createAgentRegistry</code>, <code>materializeAgent</code> and <code>agentBlock</code> from <code>@flow-state-dev/workforce</code> (<code>packages/workforce/CHANGELOG.md</code>), and with them <code>materialize-agent.ts</code>, <code>resolve-persona.ts</code> and <code>resolveAgentPersona</code>. So the question is not which layer to take the wrapper from. There is no wrapper.</p>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thread 11 is resolved—good. Consider trimming the three “used to ask / survey got right / leaning recorded” paragraphs to a resolved thread: deletion + injection seam + hireWorkforce, with the open question only on who implements MaterializeAgentFn. Keeps tension sections from becoming duplicate changelogs.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Half of this is done in 4baa6bcc0, half is declined for the same reason as the §05 note above.

Done: the open question is now stated consistently. §10 previously said the open thread was "where materializeAgent lives (thread 11)", which contradicted this thread's own resolution a thousand lines further down. §10 now matches what you have here — somebody writes the MaterializeAgentFn, and where that implementation lives is the question to ask with the first real role block in front of us. So the page no longer resolves a thread in one place and reopens it in another.

Declined: trimming the three "used to ask / survey got right / leaning recorded" paragraphs. Same call as the §05 note — the content is accurate (I re-checked workerInputSchema, buildUserMessage, taskTools and the PersonaSource / PersonaInlineConfig locations against the tree), nothing here contradicts anything, and how much derivation a tension section should retain is the page owner's editorial call rather than a fact correction. Your "duplicate changelogs" concern is the right frame for that conversation; it just wants its own change.


Generated by Claude Code

Comment thread docs/atlas/roadmap.html Outdated
<thead><tr><th>The piece</th><th>Status</th><th>What the source actually is</th></tr></thead>
<tbody>
<tr><td>Layer&nbsp;1 packages</td><td><span class="tag t-real">exists</span></td><td><code>core</code>, <code>engine</code>, <code>orchestration</code>, and the rest of the published set. Version <code>0.0.0</code>. Releasing. Not on the market.</td></tr>
<tr><td>Layer&nbsp;1 packages</td><td><span class="tag t-real">exists</span></td><td><code>core</code>, <code>engine</code>, <code>orchestration</code>, and the rest of the published set. Publishing, pre-1.0 and not in lockstep &#8212; <code>core</code> / <code>engine</code> / <code>client</code> / <code>react</code> at <code>0.1.2</code>, <code>contracts</code> at <code>0.1.1</code>, <code>orchestration</code> / <code>workforce</code> at <code>0.2.1</code> as of this edit. Releasing. Not on the market.</td></tr>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify / staleness: Pinning concrete versions in published atlas HTML will go stale on the next publish. Unless this is generated in CI, I’d keep “pre-1.0, versions not lockstep” and point at package.json—same honesty, less maintenance.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed — fixed in 4baa6bcc0. It is not generated in CI, so the digits were guaranteed to rot on the next publish. The row now reads:

Publishing, pre-1.0 and not in lockstep — each package's own package.json carries its current version. Releasing. Not on the market.

The claim the row is actually making ("pre-1.0, publishing, not in lockstep") survives without the numbers, and the reader who wants a version now has a source that cannot go stale.


Generated by Claude Code

Comment thread docs/atlas/roadmap.html Outdated
<tr><td><code>@flow-state-dev/workforce</code></td><td><span class="tag t-real">exists</span> thin</td><td>Public package. <code>defineAgent</code>, registry, <code>materializeAgent</code>, <code>definePersona</code>. Capability factory is a stub. One example seats a skill. Not a user product.</td></tr>
<tr><td><code>@flow-state-dev/workforce</code></td><td><span class="tag t-real">exists</span></td><td>Public package, and no longer thin. The seat factory <code>hireWorkforce</code> turns <code>WORKER.md</code> records into one configured flow copy each; beside it sit <code>defineAgentWorkerFlow</code> (the built-in <code>agent</code> kind), <code>definePersona</code>, <code>resourcesFromDocs</code>, the <code>./loader</code> and <code>./codegen</code> subpaths, and the channel floor. Capability factory is still a stub &#8212; a <code>// TODO</code> returning a bare capability. The Agent factory it used to carry is <strong>gone</strong>: FIX-1344 removed <code>defineAgent</code>, <code>createAgentRegistry</code>, <code>materializeAgent</code> and <code>agentBlock</code>, and a test asserts the shipped kind imports none of them (<code>packages/workforce/CHANGELOG.md</code>, <code>packages/workforce/test/agent-worker-flow.test.ts</code>). Still not a user product.</td></tr>
<tr><td>Conductor</td><td><span class="tag t-real">exists</span> lab</td><td><code>labs/conductor/</code>, <code>private: true</code>. One phase, seed / wake / status / answer. Unpublished. Not a launched product.</td></tr>
<tr><td>Relay door</td><td><span class="tag t-real">exists</span>, as <code>dispatcher()</code></td><td>One Layer&nbsp;1 send door: address, send, no fan-out. It shipped under a different name &#8212; a block in <code>core</code>, not a group on <code>FlowDefinition</code> &#8212; so there is still no <code>packages/relay</code> and no <code>relay</code> on <code>FlowDefinition</code>, and those stopped being the test of whether the door exists. Its <code>{ id }</code> form delivers into a session that already exists. The half that has not shipped is the wait.</td></tr>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this same table edit you documented { from: true } on the dispatch row; this row still says only { id } reaches an existing session. Worth aligning so §06 doesn’t contradict itself (maybe: “existing session: { id } or reply via { from: true }—see dispatch row”).

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 4baa6bcc0. The Relay door row now reads:

Two of its SessionTarget forms reach a session that already exists: { id } names it outright, and { from: true } delivers into the stamped sender.

Verified against packages/core/src/types/dispatch.ts rather than against the neighbouring row — SessionTarget is { key } | { id } | { from: true }, and the doc comment describes from as the seam-stamped sender, read through readDispatchStamp and delivered "as an id would". So the two rows now agree, and they agree with the type.


Generated by Claude Code

Comment thread docs/atlas/conductor.html Outdated
<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 (<code>labs/conductor/src/workspace.ts</code>). The workspaces package that replaces this module has landed; the module has not moved onto it yet (section 11)</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>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Stale lab status

This row still labels provisioning as “exists · lab,” while its rewritten description correctly says the implementation moved to packages/harness-manager. The conflicting status makes the atlas unclear about which layer now owns provisioning; use the plain exists tag, as the harness-manager row does.

Suggested change
<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>

Knowledge Base Used:

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Cursor

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct, and applied in 4baa6bcc0 — the row now carries the plain exists tag, matching the harness-manager row.

Verified rather than taken on the suggestion: labs/conductor/src/workspace.ts does not exist; packages/harness-manager/src/workspace.ts does. The row's description was already right, so the tag was the only stale part.

I did not sweep the rest of the table, deliberately. labs/conductor/src/implement.ts and labs/conductor/src/flow.ts both still exist, so "Resolve inputs", "Build prompt" and "Start the run" are legitimately exists · lab.

One row is worth naming as a judgment call rather than an oversight: "Record the run" is still tagged exists · lab, and run-record.ts did move to packages/harness-manager in the same event as workspace.ts. I left the tag because that row's description makes no claim about where the module lives, so it does not contradict itself the way this one did — and the lab does still wire the collection (labs/conductor/src/flow.ts imports runRecordCollection). I did fix the stale path cited in §8's code block for it. Happy to change the tag too if you read exists · lab as a claim about ownership rather than about what the lab ships.


Generated by Claude Code

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That resolution is correct. The provisioning tag was objectively stale because the row named the old lab path and described the moved module; changing it to plain exists removes that contradiction.

Leaving “Record the run” as exists · lab is reasonable. The lab still wires the collection through flow.ts, and the row does not claim that run-record.ts remains under labs/conductor. I would only change that tag if · lab is intended throughout the table to denote implementation ownership rather than the lab’s shipped/wired surface. No further change is needed for this finding.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Following up on my own note above about "Record the run" — it changed too, in fd456e0a0. You asked the right question, so here is the answer rather than just the outcome.

I would only change that tag if · lab is intended throughout the table to denote implementation ownership rather than the lab's shipped/wired surface.

Yes — it denotes layer/ownership. The page defines the tag itself in its own legend:

exists · lab — shipped on main under labs/conductor; not yet a framework block

"Not yet a framework block" is an ownership claim, not a wiring one. The page uses it that way elsewhere too (§4's entries row: "The lab ships seed, wake, status and answer"), and the whole atlas is organised on a framework / lab / proposed axis.

That makes my earlier reasoning wrong in a specific way worth naming: I set the bar at internal contradiction — "Record the run" doesn't say where its module lives, so nothing collides. But this issue is about the page being stale against shipped code, not merely self-inconsistent. Self-contradiction is how staleness gets noticed; it isn't what makes it staleness. And run-record.ts and workspace.ts left the lab in the same event, so one row saying exists and its sibling saying exists · lab on one fact pattern teaches two rules for one thing — this issue's failure mode reproduced inside the fix for it.

So I swept all 22 tags rather than fixing the two that had been pointed at. Nine changed, twelve kept — full table with per-tag evidence in the summary comment below. The short version: the manager's own per-turn steps (workspace, verdict, ask/inbox) and the two collections are framework now; the lab's flow, entries, phase values and answer genuinely are not.

The figure labels carrying the same claim moved with them, including both aria-label clauses in §9, so the screen-reader path doesn't keep the old layer.


Generated by Claude Code

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Valid, and no further correction is needed. You’re right that the legend defines exists · lab as an ownership/layer claim (“shipped under labs/conductor; not yet a framework block”), not merely as “wired by the lab.” My earlier internal-consistency standard was too narrow.

The sweep in fd456e0a0 is consistent with the shipped boundaries: workspace.ts, run-record.ts, inbox.ts, and the manager’s per-turn decisions now use plain exists, while the conductor flow, its entries, phase values, and lab-owned answer path retain exists · lab. The corresponding figure and aria-label updates, plus the section 8 wording that the manager writes the run row, prevent the same ownership claim from surviving in prose or accessible labels. docs/atlas/conductor.html:845 is therefore correctly aligned with the page’s own taxonomy, and I have no additional finding.

Comment thread docs/atlas/conductor.html Outdated
<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>maxPending</code> bounds rows added while others are pending, 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 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>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Enqueue limit overstated

maxEnqueuedTasks is checked only when tasks are created, using the resulting number of pending rows. Later unblock, unpark, and reclaim transitions can exceed it, so saying it bounds how many rows may be enqueued “at once” teaches a steady-state guarantee the option does not provide. Describe it as an enqueue-at-creation limit instead.

Suggested change
<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 how many pending rows a task creation may leave behind but is not a steady-state limit (<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>

Knowledge Base Used: Task orchestration and task boards

Fix in Cursor

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct — fixed in 4baa6bcc0. Codex found the same thing independently, which is a good signal the old wording really did read as a steady-state guarantee.

I took the finding but not the suggested wording. The sentence now reads:

maxEnqueuedTasks bounds a single up-front fan-out burst — checked at creation against the resulting pending count, so it refreshes as tasks drain (packages/orchestration/src/tasks/collection/task-caps.ts — this thread previously called it maxPending, which is not a board option and never was)

Two deliberate differences from the suggestion:

  1. It says what the cap does bound rather than leading with what it doesn't. "Bounds a single up-front fan-out burst" is task-caps.ts's own phrase, and a reader who has it derives the rest; "but is not a steady-state limit" buries the point in a negation.
  2. The citation moved to task-caps.ts, which is where the cap semantics live. task-board/index.ts is only where the option is declared. That module also asks to be cited rather than restated ("## Lifetime — the canonical statement (cite this, don't restate it)"), so the atlas points at it instead of paraphrasing the whole cap model.

Kept the maxPending parenthetical — that part was correct and is this thread's own earlier correction.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 698019ff4b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/atlas/conductor.html Outdated
<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>maxPending</code> bounds rows added while others are pending, 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 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>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Describe maxEnqueuedTasks as a creation-time bound

The new wording presents maxEnqueuedTasks as a hard bound on how many rows can remain enqueued, but packages/orchestration/src/task-board/index.ts and packages/orchestration/src/tasks/collection/task-caps.ts explicitly limit it to task creation against the current pending count. Retries, unpark/unblock, resume, and lease reclamation can re-pend rows without this check, so the pending count may exceed the configured value. Describing it as a continuous bound in this concurrency-design thread could cause later work to rely on queue-depth protection that does not exist.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed and fixed in 4baa6bcc0. You and Greptile found this independently.

Your framing of the risk was the part that decided how to word it — the danger isn't the inaccuracy in isolation, it's that a later spec in this same concurrency thread leans on queue-depth protection that doesn't exist. So the replacement says what the cap does bound rather than qualifying the old claim:

maxEnqueuedTasks bounds a single up-front fan-out burst — checked at creation against the resulting pending count, so it refreshes as tasks drain (packages/orchestration/src/tasks/collection/task-caps.ts …)

Citation moved to task-caps.ts, since that is where the semantics live and it explicitly asks to be cited rather than restated. Full reasoning on the Greptile thread.


Generated by Claude Code

Comment thread docs/atlas/conductor.html
<p>Start with the constraint, because it is why this section exists. <code>ctx.suspend</code> pauses <em>the request that calls it</em>. A detached worker's parent has already returned &#8212; the row is <code>in_progress</code> and the parent's <code>terminationReason</code> is <code>"handed-off"</code>. If a run suspends, the run pauses and nothing else does. You are never told. The epic keeps running around a run that is quietly waiting for a person who does not know they are needed.</p>

<p>And nothing refuses the call, which is the half worth saying out loud rather than assuming. A fence making <code>ctx.suspend</code> an error inside a run is decided and filed <span class="tag t-prop">proposed</span> &#8212; it is not built, and section 11 is where it sits. Until it lands the wrong mechanism stays reachable and fails quietly, which is an argument for building the right one rather than for waiting on the fence.</p>
<p>And nothing refuses the call, which is the half worth saying out loud rather than assuming. A fence making <code>ctx.suspend</code> an error inside a run was filed as FIX-1247 and has since been <strong>cancelled</strong> <span class="tag t-gone">cancelled</span> &#8212; it is not built, nothing on the tracker will build it, and section 11 is where that sits. The wrong mechanism stays reachable and fails quietly <em>permanently</em>, not until a fence lands, which sharpens rather than weakens the argument for building the right one.</p>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Update the figure when marking the fence cancelled

Changing FIX-1247 to cancelled here leaves the immediately adjacent figure stale: its visible text still labels the fence PROPOSED, its aria-label says it is “filed but not built,” and the caption still calls it a “filed, unbuilt fence.” Consequently visual and screen-reader users receive the tracker status this commit is intended to correct; update those three figure representations alongside this paragraph.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed and fixed in 4baa6bcc0 — you and Cursor found this independently, which is why it got weighted first.

All three representations now match the prose: aria-label says the fence "was filed and then cancelled, so nothing refuses it and nothing on the tracker will"; the visible text reads CANCELLED — NOTHING WILL MAKE THIS AN ERROR (and moved from f-accent to f-gone); the caption says "the fence that would have was cancelled, and nothing on the tracker will build one".

Your point about the visual/screen-reader split is the one that made the aria-label a separate fix rather than an afterthought. Detail on the Cursor thread, including a fourth string in the same figure that had the same problem in the other direction.


Generated by Claude Code

…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

Copy link
Copy Markdown
Collaborator Author

Review addressed in 4baa6bcc0. Replies are on the threads where each finding was raised; this covers the two things that had no thread, plus verification.

Stale cited paths — swept, not spot-fixed

§9's inbox code block cited labs/conductor/src/inbox.ts, which no longer exists. It is packages/harness-manager/src/inbox.ts. Rather than fix just that one, I grepped both pages for every labs/conductor/src/ citation and checked each against the directory. That turned up a second stale path nobody had flagged: §8's run-record block cited labs/conductor/src/run-record.ts, also moved to packages/harness-manager. Same event as the workspace.ts move.

Both now cite the real path and drop the · LAB label. The surviving citations — flow.ts (×4), implement.ts, answer.ts, config-env.ts — all exist and are correctly labelled.

I kept "Narrower than this page proposed" on the inbox block after checking it still holds: the shipped questionStateSchema is exactly the six fields the page lists, and kind, options, requestId and client.live are indeed absent. Likewise the run-record block's claim about scope: "user" with no sharedToLineage — that is what ships.

Verification

Re-grepped both files after editing for fence, FIX-1247, PROPOSED, materializeAgent, { id }, maxEnqueuedTasks and labs/conductor/src/, and checked every surviving hit rather than treating an empty result as proof. Verdicts:

Term Surviving hits Verdict
fence §6 prose ×2, §11 list, §11 table, plus "ticket-fenced recorders" correct — all say cancelled/permanent, consistently
FIX-1247 4 (L788, L862, L1852, L1894) correct — all four say cancelled
PROPOSED 8 in conductor, 2 in roadmap intentional — genuinely proposed-and-unbuilt items
materializeAgent L419, L446, L2065 correct — all describe it as removed
MaterializeAgentFn L446, L1728, L2066, L2068 correct — §10 now matches thread 11
{ id } roadmap L491, L496 fixed — both list both SessionTarget forms
maxEnqueuedTasks L1698, L2135 fixed at L2135; L1698 only names the caps, no semantic claim
labs/conductor/src/ 7 correct — every path exists

The greps reach the changed text (they return the edited lines, not just the untouched ones). Both files still parse with zero unclosed tags; I confirmed that check can fail by running it against a deliberately broken copy, which reported 33 errors.

Not done

Two Cursor threads asking to collapse accretion-voice notes (§05 materializeAgent survey, §12 thread 11) are declined with reasoning on each. Neither contradicts anything — the facts check out — so they are concision calls on a page that deliberately shows its derivation, and that belongs in its own editorial change rather than mixed into fact corrections. Flagged there for the page owner.

One judgment call worth a second opinion: the "Record the run" row is still exists · lab although run-record.ts moved out of the lab, because unlike "Provision workspace" that row makes no claim about where the module lives and the lab does still wire the collection. Noted on the Greptile thread.

No changeset — docs/atlas/*.html are hand-maintained pages with no published-package consumer affected (BP-022).


Generated by Claude Code

…1437)

`exists · lab` is a layer claim — the page's own legend defines it as
"shipped on main under labs/conductor; not yet a framework block". Several
rows still carried it for modules that now ship in packages/harness-manager,
which the lab only consumes.

Swept all 22 tags. Nine changed to the plain `exists` tag:

- Record the run, and the runs/** collection row — run-record.ts is in
  packages/harness-manager, not the lab. Same move as workspace.ts, so the
  two rows now follow one rule.
- The inbox collection, in both the section 9 prose and the collections
  table — inbox.ts moved with it.
- Provisions the workspace, Decides (settle/retry/wait/ask), and Posts a row
  to the inbox — the manager's own per-turn steps, in manager.ts and ask.ts.
- The claim-predicate clause in section 9, which states a framework fact that
  section 4 already tags plain `exists`.

Twelve keep the tag: the legend itself, the conductor flow and its entries,
the epic-derived collection id, resolve-inputs, build-prompt, start-the-run,
the lab's answer, the phase values, boardId derivation, and config-env —
all still in labs/conductor/src/.

The same claim appears in figure labels, so those move too, including both
aria-labels so the screen-reader path does not keep the old layer: the
harness-manager and inbox labels in sections 6 and 9, and the runs-row label
in section 5.

One prose fix where the tag change would otherwise contradict the sentence
beside it: the section 8 run-record line said "the lab copies it to the
runs/** row". The manager does (manager.ts writes sessionId onto the row);
the lab only declares the resource.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt

jhoffner commented Sep 18, 2026 •

Copy link
Copy Markdown
Collaborator Author

Follow-up in fd456e0a0, amended by e514fc4ab: swept every exists · lab tag in conductor.html against shipped code, not just the two that were pointed at. Reasoning is on the Greptile thread; this is the evidence.

Amended. This comment first said "All 22 tags resolved, none left unresolved" with an 9-changed / 12-kept split. That was wrong: L1499 carried two claims under one tag and I resolved only the visible one. Corrected below — 11 changed, 11 kept — and the reasoning is in the follow-up comment. Leaving a stale count inside the fix for stale counts would have been its own joke.

The rule: the page's own legend defines exists · lab as "shipped on main under labs/conductor; not yet a framework block" — a layer claim. The lab's surviving modules are answer.ts, config-env.ts, flow.ts, implement.ts, index.ts, patterns.ts. Anything a row describes that now lives under packages/ takes the plain exists tag.

Changed — 11

# Line What it tags Evidence
1 848 Record the run packages/harness-manager/src/run-record.ts; no labs/conductor/src/run-record.ts
2 951 Inbox collection's user scope packages/harness-manager/src/inbox.ts
3 953 Claim-predicate clause isClaimable / applyClaimToTask are packages/orchestration; §4 tags the same fact plain exists
4 1328 Provisions the workspace packages/harness-manager/src/workspace.ts
5 1331 Decides: settle, retry, wait, ask manager.ts L1327+ is the decide step; lab defines no verdict logic
6 1332 Posts a row to the inbox packages/harness-manager/src/ask.ts + inbox.ts
7 1333 Run-record session-handle copy manager.ts writes sessionId onto the row (L1512, L1550)
8 1539 inbox/** collection row as #2
9 1541 runs/** collection row as #1
10 845 Provision workspace (run-anatomy row) fixed in 4baa6bcc0, the finding that started this
11 1499 Phase surface + its header header is packages/harness-manager/src/manager.ts:14 — ## The phase surface is options, not a record type. Split: framework surface takes exists, the lab's call site (flow.ts:550) keeps exists · lab

Kept — 11

# Line What it tags Evidence
1 228 The legend defining the tag it is the definition
2 766 The conductor flow labs/conductor/src/flow.ts
3 770 The entries (seed/wake/status/answer) flow.ts + index.ts barrel
4 772 Epic-derived collection id / boardId tag attaches to "The lab locks exactly this: labs/conductor/src/flow.ts derives…"; confirmed at flow.ts:514
5 844 Resolve inputs labs/conductor/src/implement.ts
6 846 Build prompt phase logic = implement.ts
7 847 Start the run the seat, in flow.ts
8 1030 Lab's answer (beside framework exists) labs/conductor/src/answer.ts
9 1439 answer behaviour today as above
10 1701 boardId derived from the epic as #4
11 1723 Policy read from the environment tag attaches to the labs/conductor/src/config-env.ts citation

For #4 and #11 the tag sits at the end of a long row, so I checked what it attaches to rather than reading the row's opening subject. Both genuinely tag a lab claim.

No tag is now unresolved. The one needing a tiebreak was #3 (line 953) — it cites no path, so I resolved it by what the clause describes: the board's claim-pool semantics, which are framework, and which §4 already tags plain exists. Tagging one fact two ways is the thing this issue is about.

Figure labels carrying the same claim

The tag also appears as SVG text, so those moved with it or the diagram would keep teaching the old layer — the same three-place problem as the §6 fence. EXISTS · LAB on the harness manager (§6 and §9) and on the inbox collection, and A runs/** ROW · LAB in §5. Both aria-label clauses in §9 too ("A harness manager, which the lab ships" → "which ships in the framework"; same for the inbox), plus §3's "which the lab ships for one phase" → "which the lab drives for one phase". §9's third clause, "The answer entry, which the lab ships", is correct and stays.

Surviving EXISTS · LAB strings after the sweep: §5's resolve-inputs and task-seat labels, and the answer.ts code comment — all three genuinely lab.

Prose

Two sentences changed, both where a tag fix would otherwise have contradicted the words beside it: §8 said "the lab copies it to the runs/** row" (the manager does; the lab only declares the resource), and §7 said "the lab's manager" of a surface documented in manager.ts. No rows rewritten beyond that.

Both files still parse with zero unclosed tags.


Generated by Claude Code

Section 7's phase-surface paragraph carried two claims under one
`exists · lab` tag: the lab's call site, and the package's surface and
header. The header it quotes — "options, not a record type" — is
packages/harness-manager/src/manager.ts:14, a framework module, so the tag
was false about the half of the sentence that cites it.

The surface takes the plain `exists` tag and now names the module it quotes.
The lab's half keeps `exists · lab`, attached to what is actually lab: the
call site at labs/conductor/src/flow.ts:550 supplying the three values.

This is the case the sweep was for, and it slipped past because a tag at the
head of a sentence reads as covering the opening subject rather than
everything after it. The paragraph's own point — that a record type or a
registry would be abstraction for a set of one — is unchanged.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt

Copy link
Copy Markdown
Collaborator Author

Correcting my own sweep in e514fc4ab. @greptile-apps — this touches the one tag your endorsement specifically blessed, so the fact you didn't have is below rather than a verdict.

L1499 was wrong, and it's the same class the sweep was for. The paragraph was tagged exists · lab and read:

The lab's manager is constructed from exactly those three values … and its header calls the surface "options, not a record type"

That header is packages/harness-manager/src/manager.ts:14 — ## The phase surface is options, not a record type. A framework module. Under the legend's own rule ("not yet a framework block") the tag was false about the half of the sentence that cites it.

Why it survived two readings, including a sweep built to catch exactly this. The sentence carries two claims under one tag:

  • the lab's call site — labs/conductor/src/flow.ts:550 really does harnessManager({…}), genuinely exists · lab
  • the package's surface and its header — framework

Your read landed on the opening subject ("the lab's manager is constructed from…"), which is the lab half and is a correct reading of it. Mine did the same. Neither of us resolved where the quoted header actually lives, and two readings agreeing about a row's opening is not the same as either of them checking manager.ts. The defect is the sentence carrying two claims under one tag — which is also why a tag at the head of a sentence reads as covering the opening subject rather than everything after it.

Worth stating plainly, because it's this PR's own subject matter: your conceding the rule and then ratifying the artifact looks like independent confirmation and isn't — it's the same inference run twice. Not a criticism of the review; it's the failure mode the page itself keeps demonstrating.

Fixed as attribution, not a rewrite. The framework surface takes plain exists and now names the module it quotes; the lab's half keeps exists · lab attached to the call site. The paragraph's point — a record type or registry would be abstraction for a set of one — is untouched.

Two you flagged indirectly, re-checked and kept: L772 and L1723 both carry their tag at the end of a long row, so I resolved what each attaches to rather than the row's opening. L772's tags "The lab locks exactly this: labs/conductor/src/flow.ts derives…" (confirmed at flow.ts:514); L1723's tags the config-env.ts citation. Both genuinely lab.

Corrected tally: 11 changed, 11 kept. I've amended the sweep summary above, which had said "all 22 resolved" — leaving a stale count inside the fix for stale counts would have been its own joke.


Generated by Claude Code

@greptile-apps

greptile-apps Bot commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

You're right — this is a valid correction, not merely an editorial preference. The row combines two separately attributed claims: the harnessManager({…}) call site in labs/conductor/src/flow.ts:550, which remains lab-owned, and the quoted “options, not a record type” header in packages/harness-manager/src/manager.ts:14, which is now part of the framework package. Since the legend defines exists · lab as a layer/ownership claim, one tag could not truthfully cover both. Splitting the attribution and using plain exists for the framework portion preserves the paragraph's argument while removing the stale layer claim. The amended 11-changed / 11-kept tally is also the correct one; I have no further finding on this correction.

Copy link
Copy Markdown
Collaborator Author

@cursor review — your four named conditions are met as of e514fc4ab. Ready for re-review.

Happy to approve after the §6 figure + figcaption + §10 note + roadmap Relay row are brought in line with the prose you already updated.

Your condition Commit What it says now
§6 figure aria-label (~L866) 4baa6bcc0 "filed and then cancelled, so nothing refuses it and nothing on the tracker will"
§6 visible label (~L884) 4baa6bcc0 CANCELLED — NOTHING WILL MAKE THIS AN ERROR, moved f-accent → f-gone so the colour carries the status too
§6 figcaption (~L891) 4baa6bcc0 "the fence that would have was cancelled, and nothing on the tracker will build one"
§10 note (~L1728) 4baa6bcc0 Matches thread 11: somebody writes the MaterializeAgentFn, and where that lives is the question for the first real role block
roadmap Relay door row 4baa6bcc0 Both SessionTarget forms, verified against packages/core/src/types/dispatch.ts rather than against the neighbouring row

Your method was the right one and we used it verbatim — grep for fence, FIX-1247, PROPOSED, materializeAgent lives, then replace or delete. §11's meta-instruction is deleted rather than reworded: once the figure agrees with the prose there is nothing left to treat as lapsed.

Two things your review didn't ask for, both found by grepping as you suggested:

  • §6 L878 read THE FRAMEWORK VERB IS SPECCED, NOT BUILT — contradicting its own aria-label and §8's exists tag. board.unparkAndDrain ships. Now FRAMEWORK SHIPS board.unparkAndDrain.
  • The exists · lab tags had the same rot: 22 of them, checked against the legend's own definition ("shipped on main under labs/conductor; not yet a framework block"). 11 changed, 11 kept — workspace.ts, run-record.ts and inbox.ts left the lab with the manager. Figure labels and both §9 aria-label clauses moved with them, so the screen-reader path doesn't keep the old layer.

Pinned versions (roadmap.html L489) took your suggestion as written — the row now points at each package's own package.json. You were right that it was worse than the 0.0.0 placeholder it replaced: a wrong-looking number gets checked, a plausible one doesn't.

Declined, with reasons on each thread: collapsing the §1 and thread 11 accretion paragraphs. The facts there check out and neither contradicts anything, so it's a concision judgment rather than a staleness defect — and how much derivation this page keeps is its owner's editorial call, not something to settle inside a review round on staleness. Your "duplicate changelogs" framing is the right frame for that conversation; it's queued as its own pass so the diff can be read as prose.

Your machine-checkable-claims suggestion is noted as follow-up, not folded in here — two throwaway checkers (cited paths resolve; cited identifiers exist) already ran over all four atlas pages for this PR, both proved red before any green was trusted. Making them permanent is the right next step and wants its own change.

Scope note: workforce.html and framework.html carrying the same removed-factory rot is tracked — see "Found, not folded in" in the description, filed as FIX-1441.


Generated by Claude Code

@cursor

cursor Bot commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Skipping Bugbot: your auto mode classified this PR to skip. Visit the Bugbot dashboard to update your settings.

@jhoffner
jhoffner merged commit 7ac66fc into main Sep 18, 2026
12 checks passed
@jhoffner
jhoffner deleted the fix/FIX-1437-atlas-staleness branch September 18, 2026 20:01
jhoffner pushed a commit that referenced this pull request Sep 18, 2026
Three reviewers found three structurally distinct joints at which the
enumeration rule could not bind. None overlaps, and each is folded:

- hook (Cursor): "the two sweeps" was satisfiable by grepping and glancing.
  The sweeps are now named — word sweep, surface sweep — and the report must
  say whether enumeration ran and over what.
- gate (Codex): the paragraph opens "before closing a round that changed
  behavior", and #1886 and #1898 changed no behavior. The rule for a stale
  aria-label sat behind a gate excluding every case it came from. Broadened to
  any corrected claim or documentation change.
- unit (Greptile): enumerating a surface still resolves each label's opening
  subject, which is exactly how #1886's L1499 survived a 22-tag sweep. Every
  claim under a label must be resolved, and the label split where they differ.

That is the entry's own thesis landing on the entry, observed rather than
inferred, and it replaces the six-cycle count as cycle 13's result. The
recommendation does not move — one checklist line is still the right altitude —
but its claim is weaker and the entry says so: what landed is the line plus
three rounds of adversarial review, and only the first half is reproducible.
The measured failure mode is reachability, not wording, so claim 1 measures
that first and claim 6 carries the reachability check as a candidate rather
than minting it on one sitting's evidence.

Also corrected, all found in review and all the same class:
- the duplicate #1718 row (it already has one at cycle 10, and a row recording
  zero delta double-counts the epic); the observation moves to prose
- "pnpm typecheck runs five sibling guards" — it runs three; the five
  docs-corpus guards are in CI, which is where the orphan guard belongs
- "all three live inside one <svg>" two clauses before the same sentence says
  <figure> correctly; zero figcaptions sit inside an svg anywhere in docs/atlas
- the ledger blockquote, relabelled as-landed and resynced to the folded text

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants