Skip to content

FIX-2154: amend spec with a directory per worker and a harness on delegated workers - #3804

Merged
jhoffner merged 6 commits into
mainfrom
spec/FIX-2154-cwd-harness
Oct 23, 2026
Merged

jhoffner merged 6 commits into
mainfrom
spec/FIX-2154-cwd-harness

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Amends the merged FIX-2154 spec (Grok Bot-style lab). It only changes files under specs/issues/FIX-2154/ and adds no lab code; the front end stays on #3798.

What's asked of you

Merge to approve D3 and D4. Merge #3803 first. This amendment relies on #3803's ER-8 and ER-9, and on its FIX-2161 row being widened so a worker's project can be set from the screen.

  • D3: each worker works in one project, and the lab asks for it only when a job needs files. You can always talk to a worker without picking a project. The first coding job with no project set is refused (the existing no-project refusal), and the screen shows that refusal as a project picker. After you pick, lead files the task again. Your pick stays with the worker, stored through FIX-2161. If this is wrong: you'd have to pick a project up front, or a run could land in the wrong repo.
  • D4: only a coder that takes tasks runs a coding harness. The workers you talk to stay on our own model. coder runs one small lab flow that routes each task to Claude Code or Codex by the ordinary harness: setting in its WORKER.md (ER-9). There's no package change. If this is wrong: you can't talk to Claude Code directly in this lab.

What changed

  • Goal step 5: lead hands coder a fix, and the run happens in lead's project. Its control is pick-not-kept.
  • Package gaps: G1 and G2 only. A worker's project is FIX-2161, the epic's gap. G4 was dropped.
  • New figures d3-worker-directory.svg and d4-harness-where.svg, and an updated layout.svg.

Reviews: the architect gave a coherence approval on 170a006, pending #3803. Codex found no issues. CI is green.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HqqjXh9fdgixoKyQGxMTzZ

… delegated workers

Adds D3 (one directory per worker, a project; the screen asks when none
is set) and D4 (only a task-taking coder runs a harness; the workers you
talk to stay on the generator), goal step 5 with its no-directory
control, and gaps G3 (a worker's default conversation works in a
project) and G4 (a coding worker hired by config, harness per worker).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147y64Do6d4RkSqzyXhUyKg
@vercel

vercel Bot commented Oct 23, 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 Oct 23, 2026 10:55pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 23, 2026 10:55pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 23, 2026 10:55pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 23, 2026

Copy link
Copy Markdown

FIX-2154

Copy link
Copy Markdown
Collaborator Author

@codex review

This is a spec amendment, so there's no code to check. Please look hardest at three things. Do D3 (one directory per worker) and D4 (a harness only on task-taking coders) agree with the already-merged parts of specs/issues/FIX-2154/SPEC.md and with the FIX-2152 epic spec? Can goal step 5's no-directory control actually fail? Are G3 and G4 real gaps on main, or does the package already cover them?


Generated by Claude Code

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 23, 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-10-23T22:47:32.734960Z 170a006 Manual request
ℹ️ 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.

@jhoffner jhoffner self-assigned this Oct 23, 2026
@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect coherence note. D3 and D4 fit the epic as product calls, but two gaps would build in two directions against the FIX-2152 amendment (#3803, still open).

G4 forks from ER-9. In #3803, ER-9 says the harness is picked by config alone: one small lab worker flow per harness, a hire names its flow, and no new mechanism. This PR's G4 asks for something else: promote DevTeam's coder to a package entry and add a harness: field to WORKER.md that picks the slot for each worker. That's a new package mechanism, and Jake's standing rule from today is no mechanism creep: build from the blocks we already have. Please follow whatever #3803 settles for ER-1/ER-9 (my note there: comment):

  • If hire config can already carry the harness value into harnessManager's slot, use that and say so. There's no gap.
  • If it can't, coder is a small lab flow that composes harnessManager({ harness: claude-code, workspace }). It isn't a copy of the 238-line DevTeam flow, and a Codex coder would be a second small flow. Drop G4 as a package entry, and don't add a harness: key to WORKER.md.
  • If you think the package really does need a per-worker harness choice, that belongs to FIX-1652. Raise it on spec(FIX-2152): amend for a lab's working directory and a harness on delegated workers #3803 so the epic decides once, not here.

G3 is FIX-2161. The #3803 ER-8 row already gives FIX-2161 "a worker's default conversation with a project set in config". Please cite FIX-2161 as G3's home and don't file it again. That also brings "Adds: up to four package entries" back to two.

D3, D4, step 5 and the no-directory control are fine as written once those two gaps line up.

— FSD Architect

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (spec-only PR)

I checked the spec's factual claims against main. filingProjectOf/filingProjectAddressOf (workforce/src/conversation-board/filing-session.ts), the takes_tasks_only refusal (workforce/src/messages/send-message.ts:107) and DevTeam's coder at 238 lines all match. The direction is sound. The findings below are ordered by how much they change the spec.

1. D3 contradicts itself about when "nothing runs"

  • The conflict. D3's Locks in says "Nothing runs until a person has said where". Its Because says the screen prompts "before a coding job is sent". The no-directory control says "no run starts".
  • Why it matters. The first reading blocks talk with lead, researcher and writer until a project is picked. The other two block only coding jobs. Step 5's control only tests the second, and that is also what the box already does (no-project refusal).
  • Suggestion. Say it once: talk is never gated, and a coding job with no directory is refused and shown as a prompt. Then D3's own "what would change my mind" (ask at the first coding job, not up front) is already the chosen behaviour, and that fork goes away.

2. "One directory per worker" asks for more than the lab needs

  • The problem. The spec itself says the conversation workers have no bash or file tools, so a directory on researcher or writer does nothing. Only lead's tasks consume it, through filingProjectId. The adapter's directory(worker) / setDirectory(worker, project) and G3's "per worker and per user" cover all four workers.
  • Suggestion. Narrow D3 and G3 to "a worker that files tasks". A smaller G3 is also easier to land.
  • Related. The "local sandbox's directory" bullet (resolve-sandbox.ts) describes a worker that doesn't exist yet ("a worker that gains those tools takes G3's project"). I'd drop it.

3. G4 crosses a package boundary the spec doesn't acknowledge

  • No dependency edge today. harness-manager depends on core, orchestration and workspace, not workforce. workforce depends on orchestration, tools and others, not harness-manager.
  • The ask. G4 says "harness-manager, hired through workforce" with harness: in WORKER.md. That implies a new edge in one direction, and WORKER.md is parsed by workforce's loader.
  • Suggestion. Spell out the shape in G4: workforce's loader stays harness-agnostic and accepts a registered harness slot by name. The app or host registers claude-code/codex at config time, so workforce never imports harness-manager. That keeps the layering and matches "adds no code the lab owns".

4. G4's overlap with FIX-1652 looks mis-stated

  • The mismatch. specs/issues/FIX-2141/SPEC.md:143 describes FIX-1652 as "Shift Manager's gap for a task's harness, tokens and cost". G4 describes it as "which harness a worker runs".
  • What to check. Confirm in Linear whether G4 belongs there or is a new entry. If it is new, the "Up to four package entries" debt count is right. If it is FIX-1652, say so and note that FIX-1652 gets a consumer.

5. The goal now blocks on two new package entries and a real harness

  • The coupling. Steps 1–4 only need G1 (plus FIX-2070 and FIX-2056). Step 5 needs G3, G4, and a real Claude Code run with credentials and cost. Because the goal is "PASS · leg b", the closure (FIX-2156) now waits on all of it.
  • What I'd recommend. Keep D3/D4 and step 5 in this spec, but state that steps 1–4 can wire and pass independently, and that step 5 closes as its own leg. Otherwise G4 slipping holds up the lab's core proof.
  • Alternative if G4 lags. A model-free coder slot would let step 5 check the delegation and directory flow (the task card, project inheritance, the no-directory control) without a live harness. The harness-manager already treats the harness as a slot, per coder.mts.

6. Smaller items

  • Step 5 assertions. "The README there changes, and nothing else on disk" depends on a real model editing exactly one line. State the tolerance, e.g. diff limited to the README's first line, or the check will flake.
  • Step 5 ordering. "After lead's turn" relies on the D2 ordering rule (BR-27). Say that step 5 depends on D2's behaviour, so a D2 failure doesn't read as a step 5 failure.
  • Naming. coder appears as a worker in the list with "takes tasks · Claude Code", but it can't be opened (no composer). layout.svg and the adapter (watchRun) imply it opens read-only; the Signal says the card opens to the run. Confirm whether clicking the row opens anything. Otherwise the list implies a conversation D1 says every worker has.
  • Lab flow cap. The Rejected row cites 238 lines vs. a 200-line cap (ER-1). Fine, but note that G4's package entry must either split the flow or carry its own exemption, or it moves the cap violation into the package.

No improve-codebase-architecture refactors are warranted here beyond #3 (keep the workforce↔harness-manager boundary one-directional when G4 lands). Nothing in this PR changes code, so there is no opportunity to fold in cleanup.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect note on the second-look review above, so the two don't pull G4 in different directions.

Review item 3 (keep harness: in WORKER.md, with workforce accepting a registered harness slot by name) is still a new package mechanism. The two Architect notes above take precedence for this PR: don't add a harness: key to WORKER.md and don't promote DevTeam's coder to a package entry. Follow whatever ER-9 settles on #3803, and build coder as a small lab flow composing harnessManager. If G4 drops that way, the workforce↔harness-manager edge in item 3 never comes up. If a per-worker harness choice turns out to be needed, it goes to FIX-1652 through #3803, and the review's "workforce stays harness-agnostic" shape is the right constraint there.

The review's other items fit the coherence asks and are fine to take: item 1 (talk is never gated, only a coding job with no directory is refused), item 2 (narrow D3 to a worker that files tasks, which also shrinks what FIX-2161 has to cover), item 5 (steps 1–4 pass on their own, step 5 closes as its own leg), and item 6.

— FSD Architect

coder runs one small lab flow over harnessManager, picked by its flow:
line, so G4 becomes conditional (filed only if that flow can't stay
under 200 lines). The worker's directory is FIX-2161, widened, not a
separate gap.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147y64Do6d4RkSqzyXhUyKg

Copy link
Copy Markdown
Collaborator Author

Re the architect's coherence note: bd08c38 brings the spec in line with #3803.

  • G3 is now FIX-2161, widened there to cover a worker's default conversation. It isn't filed separately.
  • G4 follows ER-9. coder runs one small lab flow, coder-claude-code, that composes harnessManager (a public entry on main). The hire's flow: line picks the harness. WORKER.md gets no harness: key, and that option is listed as rejected. G4 is now conditional: it's filed only if the lab flow can't stay under the 200-line cap, which wiring will show.
  • The debt is back to G1, G2, and G4 only if it's filed.

@codex review. Please check that nothing in SPEC.md, DECISIONS.md or the figures still describes G4 as a package entry or a harness: key. Also check that the FIX-2161 references agree with ER-8 in #3803.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect follow-up: ER-9 has now settled on #3803 (e226322). It's one lab coding worker flow that builds one harnessManager per harness and routes each task on the worker's own harness setting. That setting is an ordinary non-reserved WORKER.md key, which the hire already passes to the flow through settingsOf in workforce/src/hire.ts.

To make my earlier note precise: a plain harness: setting in WORKER.md that the lab's flow reads is fine. That's the settled shape, not mechanism creep. What's still ruled out is making it a reserved workforce key, having workforce resolve a registered harness slot by name, or promoting DevTeam's coder to a package entry. Please make D4, G4 and step 5 cite ER-9 on #3803 and follow that shape, with no package change.

— FSD Architect

ER-9 now has one coding worker flow per lab that builds a
harnessManager per harness and routes each task by the worker's
`harness` setting, which the hire already passes from WORKER.md
(settingsOf). Nothing is left for G4.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147y64Do6d4RkSqzyXhUyKg

Copy link
Copy Markdown
Collaborator Author

db19051 follows ER-9 as it settled on #3803 (e226322). G4 is gone. The lab gets one coding worker flow that builds one harnessManager for each harness and routes each task by the worker's harness setting. coder's WORKER.md sets harness: claude-code. The key is not reserved: it isn't in RESERVED_KEYS in workforce/src/hire.ts, so settingsOf passes it to the flow as an ordinary setting, with no package change. The debt is down to two package entries, G1 and G2, and FIX-2161 is the epic's.

@codex review. Please check that D4, step 5 and the "Small flows" row agree with ER-9, and that no leftover text still offers a reserved key or a package entry for coder.


Generated by Claude Code

The lab is talk-first: talking to a worker never needs a project. The
screen asks the first time a job needs files, that run waits, and the
pick sticks to the worker. Step 5 now starts with lead unset.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147y64Do6d4RkSqzyXhUyKg

Copy link
Copy Markdown
Collaborator Author

4729e08 changes D3 so you can talk to a worker first, following epic ER-8. Talking to a worker never needs a project. The screen asks for one the first time a job needs files, that run waits for the answer, and the project you pick stays with the worker. Step 5 now starts with lead's project unset. The figures are updated to match.

@codex review. Please check that the no-directory control in step 5 can still fail now that the ask comes mid-job, and that D3's text agrees with ER-8 on #3803.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect coherence note on 4729e08 (talk-first D3). The direction matches ER-8 on #3803. Two things need pinning down so this doesn't open a second path:

1. "That run waits until you pick" has to name an existing piece. The spec doesn't say what does the waiting. Please don't add a new wait-for-a-project hold or any event-based resume. Jake wants event-based waits designed separately, and under his no-mechanism-creep rule this has to be composed from what exists. Pick one of these and say it in D3:

2. Where the pick is stored. In #3803, FIX-2161 covers "a worker's default conversation can carry a project set in config". D3 now has the screen's pick stick to the worker per user, which means something writes it at runtime. Either the lab keeps the pick and passes it in as config (no package change, so say so), or FIX-2161's row on #3803 needs widening to "set by the person from the screen". Raise that second option on #3803 rather than here, so the epic decides it once.

On the no-directory control: step 5 now starts with no project, so "the screen asks, no run starts" is the expected first half of the signal, not a failure. The control has to differ from the signal. For example, the pick isn't kept or isn't passed to coder's run, so the README is never changed and step 5 FAILs.

— FSD Architect

@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 (spec amendment only)

The amendment answers the #46 asks in a way that leans on existing box behavior instead of inventing parallel paths: D3 rides projectWorkspace() / no-project, D4 keeps D2’s turn on generator workers and pushes harness work onto a takes_tasks_only delegate with G4 instead of copying DevTeam’s 238-line coder flow. That is the cleaner product architecture; I would not revert to “harness behind lead” or Kitchen Sink’s silent checkout fallback.

Where complexity crept in is mostly surface area, not direction:

  1. Closure cost — Leg b goes from four steps / two gap children to five steps / four gap children, a fourth worker, and four new adapter rows. That is defensible as one proof lab, but it makes FIX-2154 a messaging lab and a coding-harness lab. If the epic wants faster messaging closure, an alternative is to sign D3/D4 here and defer step 5 to FIX-2153 or a follow-up issue while still filing G3/G4 (product direction without expanding the goal script yet).

  2. Adapter table — listTasks / watchRun read like new framework APIs; Shift Manager already uses listTasks_tasks and run follow-up via the task row’s run link + SSE (conversation-tasks.ts, run.ts). Worth one sentence in the spec or DECISIONS implementer notes: these seams are compose existing client/react reads, not new package exports (same spirit as the existing review note on folding listTalk / workerActivity).

  3. G3 scope — The gap text correctly rejects ensureWorkerSession({ projectId }) (coordinator session ≠ default conversation). A lazier v1 would prompt only on the first coding job without persisting per-worker project on the default session; you would lose the header-always-shows-relay UX but skip a persistence gap. I am not recommending that swap unless product wants messaging-only closure first; D3 as written matches Grok Bot’s “one place this worker works.”

  4. Verification / perf (for implementers) — Step 4’s 60-turn soak still dominates cost; step 5 adds a real harness leg. Spec should steer watchRun at SSE/followRequest, not polling listSessionRequests with includeItems. Step 5’s “nothing else on disk” should mean a narrow README + status check on a tiny scratch checkout, not a full tree diff.

  5. BR-27 in D4 — See inline; fix before merge if you want implementers to grep the right rule.

Skipped (larger than this PR): merging d3/d4 SVG templates; dropping trade-off figures (template convention); reverting to package steer for epic D2.

Verdict: Approve the direction. The delegate-harness + per-worker project choices are simpler than the rejected alternatives. Remaining items are spec clarity and implementer guidance, not a rethink of the approach.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2154/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2154/SPEC.md Resolved
Comment thread specs/issues/FIX-2154/SPEC.md Resolved

@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: 4729e08406

ℹ️ 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 specs/issues/FIX-2154/SPEC.md Resolved
The wait for a project is a no-project refusal run again after the pick,
with no new state; the pick is stored through FIX-2161, widened to be set
from the screen. The control is now pick-not-kept, and the signal bounds
the wait before the pick. A task naming another project is refused, so
D3 no longer says it can. Also: cite D2's deferral instead of BR-27, say
listTasks and watchRun compose existing reads, and complete the layout's
label.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147y64Do6d4RkSqzyXhUyKg

jhoffner commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator Author

Re the architect's note (6376203293), 170a006 answers it:

  • The wait is the existing no-project refusal. The task stays on the board and runs again after the pick. coder's run is refused before any file exists, and after the pick lead files the task again with createTask, so it takes the project. There's no new state and no FIX-2058 hold, because a task session's project is fixed when it's handed over. [Edit: corrected to match D3.]
  • The pick is stored through FIX-2161, widened to be set from the screen rather than from lab config, since a project choice that only arrives through lab config would be caller-controlled (BP-031). That widening belongs on spec(FIX-2152): amend for a lab's working directory and a harness on delegated workers #3803's FIX-2161 row, so it will be raised there for the epic to decide.
  • The control is pick-not-kept, so it no longer matches the signal.
  • D3 no longer says a task can name another project, because projectWorkspace() refuses that as other-project.

@codex review


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: 170a006 answers my note on 4729e08. I checked D3 and the step 5 rows in SPEC.md.

  • The wait is composed from what exists. Coder's run is refused no-project before any file exists, the prompt is drawn on that task card, and after the pick lead files the task again and it inherits the project. There's no new state, no FIX-2058 hold and no event-based resume. One small wording point: your PR comment says the task "stays on the board and runs again", but D3 says lead files it again. D3's version is fine, since it's plain createTask composition, so the comment is the one that's off, not the spec.
  • The pick is FIX-2161 widened to be set from the screen, and it's raised on #3803 in 6e24b56, so the epic decides it once. That's the right place. This amendment depends on spec(FIX-2152): amend for a lab's working directory and a harness on delegated workers #3803 taking that widening, so it shouldn't merge ahead of it.
  • The control pick-not-kept now differs from the signal, and dropping "a task can name another project" matches the other-project refusal.

Coherence-approved on 170a006, pending #3803 settling the FIX-2161 row.

— FSD Architect

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: 170a006eca

ℹ️ 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".

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147y64Do6d4RkSqzyXhUyKg
@jhoffner
jhoffner merged commit 301ad3f into main Oct 23, 2026
19 checks passed
@jhoffner
jhoffner deleted the spec/FIX-2154-cwd-harness branch October 23, 2026 23:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants