Skip to content

docs(atlas): fold Workforce readiness gaps into §03 / §18 - #1626

Merged
jhoffner merged 1 commit into
mainfrom
cursor/atlas-workforce-astra-gaps-44d2
Sep 7, 2026
Merged

jhoffner merged 1 commit into
mainfrom
cursor/atlas-workforce-astra-gaps-44d2

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 7, 2026

Copy link
Copy Markdown
Collaborator

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

1. Honesty. Reverse { from: true } stays exists. Cross-flow stays proposed (#1600 open). Existing-session past a queue stays a named refuse. Instances stay first-wins on this pin.
2. Named gaps, not a fifth slice. Conversation, board-as-address-test, durable delegation, and materializer are gaps 7–10 on the existing inventory. Sequence sits on §03 as a band, not a new foundation.
3. POC-ready, taught honestly. Static-target board notify can lab now. Multi-instance conversation waits on INST-1..3. Dynamic-address composition waits on #1600.
4. Prior locks. Seat / worker / Agent, thin L1 Agent seam, teams/ tree, projects-as-resources, invent kills — unchanged.

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
  • docs(atlas): seat binds a worker; product Agent is L2 #1614 merged, so a new PR rather than a fold-in.
  • Pin moved to d8899c9b5 (2026-09-07), the merge of docs(atlas): seat binds a worker; product Agent is L2 #1614.
  • Grep on this pin: cross-flow refuse still on create-request-host.ts. { from: true } exists. flow-registry.ts get(kind) still first-wins. Skills delegation still backing: "sequencer". materializeAgent still requires skillName / workerKey, forces z.string(), can skip capabilities with no catalog. dispatch.ts: a target chosen from data is a router over declared dispatchers, not a dynamic address.
  • FIX-1315 is Duplicate of FIX-1322 / absorbed into FIX-1320. The page says so.
  • framework.html gets one pointer at workforce.html#gaps. No new foundation there either.
Everything else

What landed

  • §03 sequence band + POC-ready note. Slice 1 now leads with FIX-1320.
  • §18 gaps 7–10 plus a sequence figure. Gap 1 retitled to FIX-1320.
  • §16 honesty on materializeAgent and definePersona.
  • Prior locks left in place.

Verification: HTML parses (empty stack, no mismatch) on both files. Section numbers 01–20. Exists-tagged invented names: none. Cross-flow not tagged exists.

Open in Web Open in Cursor 

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>
@vercel

vercel Bot commented Sep 7, 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 7, 2026 4:13pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 7, 2026 4:13pm UTC
flow-state-dev-ui Ignored Ignored Sep 7, 2026 4:13pm UTC

Request Review

@jhoffner
jhoffner marked this pull request as ready for review September 7, 2026 16:29
@jhoffner
jhoffner merged commit cc4bd1e into main Sep 7, 2026
12 checks passed
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 7, 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-07T16:31:00.313707Z 69a3588 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

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.html cross-link — one sentence + #gaps; matches how roadmap.html defers 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:

  1. Drop or shorten the §03 READINESS SEQUENCE SVG band — it mostly duplicates §18 lede + the new §18 figure. A See §18 pointer in the band (or figcaption only) is enough orientation.
  2. Keep the §18 sequence SVG — it adds POC-ready nuance the §03 band doesn't.
  3. §02 "Phased implement" — compress to "unblockers per §18" rather than restating the full chain.
  4. 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.
  5. Gap 10 vs §16 — materializeAgent symptoms are already in the #exists row (~2211). Gap 10 can be FIX-1327 link + "before teams harden; see §16" instead of re-listing bullets.
  6. 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.
  7. 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).
Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread docs/atlas/workforce.html
<text class="t-lbl" x="34" y="402">CUT &#183; KILL INVENT</text>
<text class="t-s" x="34" y="426">no TeamFlow / Channel / MessageBoard L1 &#183; no second Agent &#183; 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 &#183; NAMED GAPS, NOT A FIFTH SLICE</text>

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.

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.

Comment thread docs/atlas/workforce.html
<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&#8217;s knowledge. That is tenet&nbsp;4.</td><td>Invent a primitive the substrate does not have. Compose, or file a Layer&nbsp;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&#8594;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&#8594;4 build-out. The readiness sequence is named gaps on that inventory &#8212; not a fifth slice. Conductor also cares about the L1 slice. It does not wait on Workforce product.</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.

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.

Comment thread docs/atlas/workforce.html
<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.">

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.

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.

Comment thread docs/atlas/workforce.html
<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 &#8594; B &#8594; <code>{ from: true }</code> reply &#8594; later messages into the <em>existing</em> session. Layer&nbsp;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&nbsp;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 &#8212; <code>dispatch.ts</code> says a target chosen from data is a router over declared dispatchers, not a dynamic address. Need that Layer&nbsp;1 composition explicit before Workforce mints a &#8220;dynamic dispatcher.&#8221; 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>) &#8212; 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 &#8212; do not sequence it here.</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.

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.

Comment thread docs/atlas/workforce.html
<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 &#8212; 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/&lt;teamId&gt;/workers/&lt;name&gt;/</code>). No such tree on main. Scan&#8594;<code>defineFlow</code> is a named gap &#8212; 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&#8594;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&#8217;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 &#8212; 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/&lt;teamId&gt;/workers/&lt;name&gt;/</code>). No such tree on main. Scan&#8594;<code>defineFlow</code> is a named gap &#8212; 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&#8594;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&#8217;s L1 under Workforce as if foundation shipped. Inventing the loader as an export. Hardening teams on the skill-forced materializer.</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.

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.

Comment thread docs/atlas/framework.html
<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&nbsp;1 primitive. A roster is the seat-list; a team is that roster plus shared rooms plus dispatch as Layer&nbsp;2. A seat binds a worker, not an Agent. Product Agent is Layer&nbsp;2. The core <code>Agent</code> / <code>AgentRegistry</code> types are the thin seam &#8212; 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&nbsp;1 primitive. A roster is the seat-list; a team is that roster plus shared rooms plus dispatch as Layer&nbsp;2. A seat binds a worker, not an Agent. Product Agent is Layer&nbsp;2. The core <code>Agent</code> / <code>AgentRegistry</code> types are the thin seam &#8212; 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 &#8212; <a href="workforce.html#gaps">&#167;18</a> &#8212; not as new Layer&nbsp;1 nouns.</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.

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.

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