Repository navigation
docs(atlas): fold Workforce readiness gaps into §03 / §18 - #1626
Conversation
Name conversation-through-dispatch, board-as-address-test, durable delegation, and materializeAgent cleanup as gaps on the existing inventory. Sequence instances first (FIX-1320). No new L1 nouns. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
Simplify review
Problem this PR solves: Workforce readiness (conversation, board proofs, durable delegation, materializer) needed a home without minting new Layer 1 nouns. Folding gaps 7–10 onto the existing §18 inventory and cross-linking from framework.html is the right architectural call — same pattern as prior atlas locks (four slices teach, §18 pins refuses).
Verdict: Direction is sound; packaging adds more repetition than the page can sustain. Not blocking merge, but a trim pass would materially reduce drift risk.
What landed well
- Named gaps, not a fifth slice — consistent with §04 fence and the page's own SSOT language (§17: "link here, don't re-litigate").
- FIX-1315 → FIX-1320 consolidation — fewer parallel tracks.
framework.htmlcross-link — one sentence +#gaps; matches howroadmap.htmldefers to siblings.- Gap 5 ↔ gap 7 relationship — "session-addressability half of gap 7" is good internal reuse.
Where complexity crept in
The readiness sequence (instances → conversation+board → delegation → materializer) now appears in five+ places: §02 "Phased implement", §03 roadmap SVG band, §03 slice table, §18 lede, §18 sequence SVG, and the one-sentence closer. Each ordering or FIX-ID change must touch most of them.
Cleaner architecture (matches conductor.html#build: tracking IDs in one section):
§03 → four slices only (teach + slice rows that cite gap numbers)
§18 → lede + gap table (SSOT) + ONE sequence visual
§02, closure, framework → "readiness: §18" shorthand
Concretely:
- Drop or shorten the §03
READINESS SEQUENCESVG band — it mostly duplicates §18 lede + the new §18 figure. ASee §18pointer in the band (or figcaption only) is enough orientation. - Keep the §18 sequence SVG — it adds POC-ready nuance the §03 band doesn't.
- §02 "Phased implement" — compress to "unblockers per §18" rather than restating the full chain.
- Stale substrate figure — the first §18 SVG still says "Five Layer 1 gaps" while the table has ten rows. Either relabel ("substrate gaps 1–5") with a caption pointing to the table for 6–10, or retire it now that the sequence figure exists.
- Gap 10 vs §16 —
materializeAgentsymptoms are already in the#existsrow (~2211). Gap 10 can be FIX-1327 link + "before teams harden; see §16" instead of re-listing bullets. - Gap 7 — gap 4's figcaption already says "LINK, DO NOT RE-LITIGATE"; gap 7 can reference gaps 1, 4, 5 by number rather than re-explaining the L1 path.
- Slice 2 vs readiness sequence — slice 2 says "Clean materializeAgent before teams harden" while §18 puts materializer after gap 9. Probably consistent (foundation cleanup before slice 3 hardens, but after delegation substrate), but one clarifying clause would prevent misread.
Gap 6 omission
Member memory (gap 6) is in slice 1 but absent from the four-beat readiness chain. If intentional (parallel track), one explicit line in §18 lede would help — otherwise readers may infer it comes after materializer.
Performance
Negligible (+~2.5 KB gz). SVGs are rect+text only. Duplication is a maintainability concern, not a load-time one.
Skipped (editorial / product call)
- Whether gaps 7–8 belong as inventory rows vs a "proof checklist" subsection.
- Whether gap 8 (
proposed · L2) belongs in an "L1 gaps" section at all. - Shortening the one-sentence summary generally (pre-existing density).
Sent by Cursor Automation: Review For Best Approach
| <text class="t-lbl" x="34" y="402">CUT · KILL INVENT</text> | ||
| <text class="t-s" x="34" y="426">no TeamFlow / Channel / MessageBoard L1 · no second Agent · no hot-dynamic kinds to paper over L1 gaps</text> | ||
| <rect class="n-prose" x="16" y="380" width="908" height="72" rx="5"/> | ||
| <text class="t-lbl" x="34" y="402">READINESS SEQUENCE · NAMED GAPS, NOT A FIFTH SLICE</text> |
There was a problem hiding this comment.
Duplication: This band restates the same four-beat chain that §18 lede (~2263) and the new §18 sequence figure (~2329) already carry. The page's own SSOT contract is "elsewhere, link here" (§18 figcaption ~2308).
Simpler: Replace the full chain with a one-line pointer — e.g. READINESS SEQUENCE → §18 — and keep the anti-pattern cuts (delivery bus / dynamic dispatcher / second store) in §18's "not a gap" note only. Saves ~80px SVG height and one sync surface.
| <tr><td>Who it is for</td><td>Authors who will compose their own harness.</td><td>Authors who want to get going, and still extend everything.</td></tr> | ||
| <tr><td>What it must not do</td><td>Absorb one product’s knowledge. That is tenet 4.</td><td>Invent a primitive the substrate does not have. Compose, or file a Layer 1 gap.</td></tr> | ||
| <tr><td>Phased implement</td><td>Unblockers first: cross-flow, same-session resume, bare-kind / per-seat, member memory scope. Cross-flow still refused on this pin.</td><td>This page names the 1→4 build-out. Conductor also cares about the L1 slice. It does not wait on Workforce product.</td></tr> | ||
| <tr><td>Phased implement</td><td>Unblockers first: instances (FIX-1320 INST-1..3), then conversation + board proofs, then durable delegation, then the materializer. Cross-flow still refused on this pin. Persona FIX-796 is independent.</td><td>This page names the 1→4 build-out. The readiness sequence is named gaps on that inventory — not a fifth slice. Conductor also cares about the L1 slice. It does not wait on Workforce product.</td></tr> |
There was a problem hiding this comment.
Duplication: The full readiness sequence in this §02 table row will drift from §18 whenever gap grouping or FIX IDs change.
Simpler: "Unblockers per §18 readiness sequence" + cross-flow refused on pin. The L2 column already says "named gaps on that inventory — not a fifth slice" — let §18 own the ordering detail.
| <figure> | ||
| <div class="fig-body"> | ||
| <svg viewBox="0 0 940 320" role="img" aria-label="Five Layer 1 gaps. Bare-kind first-registered, FIX-1315. Send-at: no due-ledger, dispatcher has no delay, scheduled envelopes have no session. FIX-1246 same-session resume still backlog. Cross-flow refuse still on main, PR 1600 open. External-dispatcher on id past a queue."> | ||
| <svg viewBox="0 0 940 320" role="img" aria-label="Five Layer 1 gaps. Flow instances FIX-1320 INST-1 through 3, FIX-1315 absorbed. Send-at: no due-ledger, dispatcher has no delay, scheduled envelopes have no session. FIX-1246 same-session resume still backlog. Cross-flow refuse still on main, PR 1600 open. External-dispatcher on id past a queue."> |
There was a problem hiding this comment.
Stale visual: aria-label and content still frame "Five Layer 1 gaps" (boxes 1–5 only) while the table below now has rows 1–10. Skimmers who stop at the SVG get an incomplete inventory.
Options (pick one):
- Relabel: "Substrate gaps 1–5 (pin refuses)" + caption "gaps 6–10: table below"
- Retire this figure now that the sequence SVG exists
- Extend to cover 6–10 (heavier maintenance)
This tension predates the PR but gaps 7–10 make it sharper.
| <tr><td>7</td><td>Full conversation through dispatch</td><td><span class="tag t-prose">blocked-on</span></td><td>The proof is A → B → <code>{ from: true }</code> reply → later messages into the <em>existing</em> session. Layer 1 path: FIX-1312 reverse <strong>exists</strong> + #1600 (gap 4) + existing-session via external queue (gap 5). Workforce must <strong>not</strong> invent a delivery bus. Blocked on #1600 + session addressability. Multi-hire also blocked on FIX-1320.</td></tr> | ||
| <tr><td>8</td><td>Board as address-model test</td><td><span class="tag t-prop">proposed · L2</span></td><td>FIX-1311 stays Layer 2 assembly: collections + subscriptions in state + <code>reactTo</code>. <code>reactTo</code> exists (in-session, inline). Pressure: addresses-as-data vs statically declared dispatch targets — <code>dispatch.ts</code> says a target chosen from data is a router over declared dispatchers, not a dynamic address. Need that Layer 1 composition explicit before Workforce mints a “dynamic dispatcher.” Teams = roster (FIX-1310). Static-target notify can lab now.</td></tr> | ||
| <tr><td>9</td><td>Durable task collections for delegation</td><td><span class="tag t-none">backlog</span></td><td><a href="https://linear.app/fixpoint-labs/issue/FIX-957">FIX-957</a>. Skills delegation still constructs the board with <code>backing: "sequencer"</code> (<code>delegation-surface.ts</code>) — turn-scoped. A hand-built durable collection already exists. Standing teams must not get a second Workforce task store. Separate from FIX-1246 (gap 3).</td></tr> | ||
| <tr><td>10</td><td><code>materializeAgent</code> cleanup</td><td><span class="tag t-none">backlog</span></td><td><a href="https://linear.app/fixpoint-labs/issue/FIX-1327">FIX-1327</a>. Before teams harden: worker shape still requires <code>skillName</code> / <code>workerKey</code>, forces <code>z.string()</code> even when <code>outputSchema</code> is set, and can skip capabilities silently when no catalog is present (BP-030 refuse, not a quiet drop). Separate skills-adapter policy from reusable materialization. Persona FIX-796 is independent — do not sequence it here.</td></tr> |
There was a problem hiding this comment.
Reuse §16: The materializeAgent symptom list (skillName/workerKey, z.string(), silent capability skip) already lives in the #exists row (~2211).
Simpler: FIX-1327. Before teams harden. See §16 materializeAgent row. + sequencing note. Keeps one source of truth for current behavior vs gap tracking.
| <tr><td>1. L1 unblockers</td><td><span class="tag t-prose">blocked-on / gap</span></td><td>Cross-flow still refused (<a href="https://github.com/fixpoint-labs/flow-state-dev/pull/1600">#1600</a> open). FIX-1246 and FIX-1315 are backlog. Member memory is a named scope gap — identity lives on agent/member, not on the seat. Same-flow DM address and <code>claim</code> already exist. Conductor cares about this slice too.</td><td>Pretending cross-flow landed. A hot-dynamic kind or TeamFlow so two seats of one kind can talk. Putting memory on the seat to skip the member-scope gap.</td></tr> | ||
| <tr><td>2. Workforce foundation L2</td><td><span class="tag t-prop">proposed</span></td><td>File conventions are this page (<code>teams/<teamId>/workers/<name>/</code>). No such tree on main. Scan→<code>defineFlow</code> is a named gap — no <code>loadWorkforce()</code>. Thin seats (intake, coordinator) stop there and skip <code>AgentRegistry</code>. <code>defineAgent</code> / registry only when the seat is an opinionated agent. Seat→worker factory is a proposed wrapper. Thin Agent opinion sits on the existing core seam; impl is already L2.</td><td>A second Agent type in the Workforce package. Scanning every seat into <code>AgentRegistry</code>. Nesting today’s L1 under Workforce as if foundation shipped. Inventing the loader as an export.</td></tr> | ||
| <tr><td>1. L1 unblockers</td><td><span class="tag t-prose">blocked-on / gap</span></td><td>Instances first: <a href="https://linear.app/fixpoint-labs/issue/FIX-1320">FIX-1320</a> INST-1..3 (FIX-1315 absorbed / duplicate). Cross-flow still refused (<a href="https://github.com/fixpoint-labs/flow-state-dev/pull/1600">#1600</a> open). FIX-1246 resume is backlog and <em>separate</em> from FIX-957 durable delegation. Member memory is a named scope gap — identity lives on agent/member, not on the seat. Same-flow DM address, reverse <code>{ from: true }</code>, and <code>claim</code> already exist. Conductor cares about this slice too.</td><td>Pretending cross-flow landed. A hot-dynamic kind or TeamFlow so two seats of one kind can talk. Putting memory on the seat to skip the member-scope gap. Inventing a delivery bus, a dynamic dispatcher, or a second Workforce task store.</td></tr> | ||
| <tr><td>2. Workforce foundation L2</td><td><span class="tag t-prop">proposed</span></td><td>File conventions are this page (<code>teams/<teamId>/workers/<name>/</code>). No such tree on main. Scan→<code>defineFlow</code> is a named gap — no <code>loadWorkforce()</code>. Thin seats (intake, coordinator) stop there and skip <code>AgentRegistry</code>. <code>defineAgent</code> / registry only when the seat is an opinionated agent. Seat→worker factory is a proposed wrapper. Thin Agent opinion sits on the existing core seam; impl is already L2. Clean <code>materializeAgent</code> (FIX-1327) before teams harden.</td><td>A second Agent type in the Workforce package. Scanning every seat into <code>AgentRegistry</code>. Nesting today’s L1 under Workforce as if foundation shipped. Inventing the loader as an export. Hardening teams on the skill-forced materializer.</td></tr> |
There was a problem hiding this comment.
Possible misread: "Clean materializeAgent (FIX-1327) before teams harden" in slice 2 vs §18 readiness putting materializer after durable delegation (gap 9).
If both are true (gap 9 is L1 substrate; slice-2 cleanup is L2 foundation before slice 3), a short clause like "after gap 9; see §18 sequence" would disambiguate. If not, worth reconciling.
| <p>Everything below workforce got built because a running system needed it. Workforce is the one layer specified top-down — the <code>Agent</code> type carries two fields nothing resolves, and its capability factory returns a name and a TODO. That is the shape tenet 3 warns about: a contract taken on before there was a caller.</p> | ||
| <p>The generous reading is that it is a placeholder held deliberately while the layers underneath matured — and they did mature; seven of the ten needs above are now met by systems that did not exist when <code>Agent</code> was first written.</p> | ||
| <p>Closed: a team is <strong>not</strong> a first-class Layer 1 primitive. A roster is the seat-list; a team is that roster plus shared rooms plus dispatch as Layer 2. A seat binds a worker, not an Agent. Product Agent is Layer 2. The core <code>Agent</code> / <code>AgentRegistry</code> types are the thin seam — do not grow them into teams or memory. Workforce story: <a href="workforce.html#fence">Workforce atlas</a>.</p> | ||
| <p>Closed: a team is <strong>not</strong> a first-class Layer 1 primitive. A roster is the seat-list; a team is that roster plus shared rooms plus dispatch as Layer 2. A seat binds a worker, not an Agent. Product Agent is Layer 2. The core <code>Agent</code> / <code>AgentRegistry</code> types are the thin seam — do not grow them into teams or memory. Workforce story: <a href="workforce.html#fence">Workforce atlas</a>. Readiness gaps (conversation, board-as-address-test, durable delegation, materializer) live on that page — <a href="workforce.html#gaps">§18</a> — not as new Layer 1 nouns.</p> |
There was a problem hiding this comment.
This is the right cross-atlas pattern — one sentence, link to #gaps, no local gap table. No change needed; other sections should follow this instead of restating sequence detail.


The Workforce atlas named the old Layer 1 doors and hid the readiness proofs Architect just fenced: a full conversation through dispatch, the board as an address-model test, durable delegation, and a materializer that still lies. A reader could invent a delivery bus, a dynamic dispatcher, or a second task store to paper over those.
Fold those as named gaps on the existing 1→4 / §18 inventory. No new Layer 1 nouns. Sequence: instances (FIX-1320 INST-1..3) → conversation + board-notification proofs → durable delegation (FIX-957) → materializer (FIX-1327). Persona FIX-796 stays independent. FIX-1315 is absorbed / duplicate.
#1614 already merged, so this is a new atlas PR.
What's asked of you
Nothing here is yours to decide. This follows Architect's fence: honesty / exists vs proposed / blocked-on / no invent.
Parts worth reviewing closely
Linear: room lock (Jake / Architect). Related FIX-1320, FIX-1312, FIX-1311, FIX-1310, FIX-957, FIX-1327, FIX-796. #1614 already merged. Atlas-only. No changeset needed.
How to review this — altitude, what's in scope, what's deliberately unsettled
This is an atlas editorial following an Architect fence. No spec, no package change. In scope: whether the page now names those gaps honestly, whether exists vs proposed vs blocked-on matches main, and whether anything claimed as existing was invented. Out of scope: landing #1600, implementing INST-1..3, shipping FIX-957, rewriting
materializeAgent.Engineering calls
d8899c9b5(2026-09-07), the merge of docs(atlas): seat binds a worker; product Agent is L2 #1614.create-request-host.ts.{ from: true }exists.flow-registry.tsget(kind)still first-wins. Skills delegation stillbacking: "sequencer".materializeAgentstill requiresskillName/workerKey, forcesz.string(), can skip capabilities with no catalog.dispatch.ts: a target chosen from data is a router over declared dispatchers, not a dynamic address.framework.htmlgets one pointer atworkforce.html#gaps. No new foundation there either.Everything else
What landed
materializeAgentanddefinePersona.Verification: HTML parses (empty stack, no mismatch) on both files. Section numbers 01–20. Exists-tagged invented names: none. Cross-flow not tagged exists.