Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions specs/epics/FIX-1903/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,15 @@ owns it and where it's checked.
| ER-3 | A project's `repository` stays a remote. The host maps a remote to a checkout on its machine for the project ids its config names ([ER-13](#what-no-child-may-do)), and a run for a mapped project is a worktree of that checkout, its branch kept there, with the project's files beside the worktree and never in it ([D3](DECISIONS.md#d3)) | FIX-1906 decides · FIX-1904 consumes | FIX-1906's tests · the closure's `git worktree list` |
| ER-4 | Two runs on two projects mapped to one checkout, at once, get two worktrees and two branches, and both settle. A test proves it, with a control that gives both runs one place and must fail | FIX-1906 | FIX-1906's tests · the closure's leg b |
| ER-5 | A project may name MCP servers, by host-approved alias ([ER-14](#what-no-child-may-do)). A coding run gets its project's servers when it starts, read from the project its own task row names, never from a hand-over's payload. A run whose project has none gets none ([D4](DECISIONS.md#d4)) | FIX-1905 decides · FIX-1904 consumes | FIX-1905's goal check, on a run not handed over by a coordinator |
| ER-6 | No credential, endpoint or credential variable is stored on a project row. A row selects MCP servers by an alias the host approves; the host config gives each alias its endpoint and the environment variable that holds its credential, and the host reads it. The value reaches the MCP connection only: not the run's environment, a log, a session or the page. The dev profile's host config has one alias, `linear`, whose variable is `LINEAR_MCP_API_KEY`, the name the kitchen-sink's Linear capability reads (`apps/kitchen-sink/lib/mcp.ts`); each person signing in to Linear as themselves is a later epic | FIX-1905 | FIX-1905's tests · its spec review |
| ER-7 | A server whose credential variable is unset is said out loud, once when the server starts and on each run that misses it. The run still runs, and that is a degraded run, not a pass: with `LINEAR_MCP_API_KEY` unset, the closure's leg a must FAIL its title check ([ER-20](#the-closure)) | FIX-1905 | FIX-1905's tests · the closure, run with the variable unset |
| ER-6 | No credential, endpoint or credential variable is stored on a project row. A row selects MCP servers by an alias the host approves, and the host config gives each alias its endpoint. The key is each person's own: set on Shift Manager's Settings page, stored as a user-scoped record in the Lab's store, write-only, shown only as set or not set. A run uses its owner's key, resolved from the server-side identity the run records, never from a field a caller sends ([BP-031](../../../docs/contributing/best-practices.md)). FSD holds the MCP connection with that key (`createMcpManager`), and the run gets the servers' tools only: the key is not handed to its command line, environment, MCP config, a log, a session or the page. It is not unreachable: an unsandboxed run can read the Lab's store. The dev profile's host config has one alias, `linear`. `LINEAR_MCP_API_KEY`, the name the kitchen-sink's Linear capability reads (`apps/kitchen-sink/lib/mcp.ts`), seeds only the Lab's operator identity, for headless and CI runs, while it has no stored key. Signing in to Linear by OAuth is a later epic | FIX-1905 | FIX-1905's tests · its spec review |

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.

ER-6 packs Settings UI, user-scoped store, createMcpManager, mcpTools, operator seed, unsandboxed caveat, and OAuth deferral into one table row. Consider splitting (credential storage vs connection boundary) or a 5-step "key path" subsection — implementers will otherwise infer FIX-1905 solely from this cell.

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 Refresh the end-state figure for per-user keys

When readers use the retained end-state figure embedded by SPEC.md, its figures/end-state.svg aria-label still says the credential lives in host config, contradicting this amended rule that credentials are per-user records and only the endpoint is host-configured. This leaves screen-reader users with the superseded security model, so update the figure and its accessibility text alongside ER-6.

Useful? React with 👍 / 👎.

| ER-7 | A missing key is said out loud: once when the Lab starts, for the operator identity, and in the session of each run whose owner has no key for a server it names. The run still runs, and that is a degraded run, not a pass: with no key on Settings and `LINEAR_MCP_API_KEY` unset, the closure's leg a must FAIL its title check ([ER-20](#the-closure)) | FIX-1905 | FIX-1905's tests · the closure, run with neither source holding a key |

## What no child may do

| # | Rule | Because |
|---|---|---|
| ER-8 | Build on the coordinator's `handOff` tool, or add an MCP or checkout field to `dispatchTask` | [D4](DECISIONS.md#d4). `handOff` retires in FIX-1872; hand-over is FIX-1870's |
| ER-9 | Add anything to Layer 1 (core, engine, orchestration). `workspace` and `claude-code` get at most one generic option each: a remote-to-checkout mapping, and per-run MCP servers | MCP settings and checkouts are Workforce and host concepts |
| ER-9 | Add anything to Layer 1 (core, engine, orchestration). `workspace` and `claude-code` get at most one generic option each: a remote-to-checkout mapping, and `mcpTools`, in-process tools relayed from FSD's connection, with no URL, command or headers. `tools` gains only a call path on `createMcpManager`. Cursor and Codex get nothing in this epic | MCP settings, keys and checkouts are Workforce and host concepts (Layer 2) |
| ER-10 | Change DevTeam's projects, workstreams, ask or coder default | [D2](DECISIONS.md#d2). Five goal checks serve its config unedited |
| ER-11 | Put a machine's path in a project row, a `WORKER.md`, or a file the published package ships | [FIX-1762 BR-5](../../issues/FIX-1762/BUSINESS-RULES.md). A path belongs to the host that has it |
| ER-12 | Migrate stored projects. A row stored before FIX-1905 reads as a project with no MCP servers | [FIX-1786 ER-31](../FIX-1786/BUSINESS-RULES.md#what-no-child-may-do): no migrations while Workforce has no consumers |
Expand Down
23 changes: 16 additions & 7 deletions specs/epics/FIX-1903/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,14 +78,14 @@ you fetch it first.
|---|---|
| **Instead of** | The coordinator attaching a project's MCP servers to the workers it hands work to, through `handOff` (retiring, [FIX-1870 D2](../FIX-1870/DECISIONS.md#d2)) or a field on `dispatchTask` · or MCP servers in a worker's `WORKER.md` |
| **Because** | A hand-over carries config only on the paths that use it: a row approved in Inbox, or filed by the chief of staff, would miss it. The run's own task row names its project on every path, and that read already gives the run its repository. A worker serves many projects, so its file can't say which tracker a project uses |
| **Locks in** | MCP servers are a project setting. Read when a coding run starts and handed to its harness; the harness gets a per-run MCP option, a generic one ([ER-9](BUSINESS-RULES.md#what-no-child-may-do)). A row names a host-approved server alias only; the alias's endpoint and the environment variable that holds its credential are host config, and the value reaches the MCP connection only ([ER-6](BUSINESS-RULES.md#what-a-person-gets-and-what-they-dont), [ER-14](BUSINESS-RULES.md#what-no-child-may-do)). A row that could name a URL and a variable could send any host secret anywhere. Coding runs only in this epic |
| **Locks in** | MCP servers are a project setting, read when a coding run starts. FSD connects to them for the run with its owner's key, and the harness gets their tools only, through one generic option, `mcpTools` ([ER-9](BUSINESS-RULES.md#what-no-child-may-do)). A row names a host-approved server alias only; the alias's endpoint is host config, the key is each person's own, set on Settings, and the key reaches FSD's MCP connection only ([ER-6](BUSINESS-RULES.md#what-a-person-gets-and-what-they-dont), [ER-14](BUSINESS-RULES.md#what-no-child-may-do)). A row that could name a URL and a variable could send any host secret anywhere. Coding runs only in this epic, Claude Code first; Cursor and Codex later |

**What would change my mind:** a worker that doesn't code (the chief of staff, the EM) turns
out to need Linear for the goal. Then those workers get the project's servers too, through the
MCP capability (`createMcpCapability` in `packages/tools/src/mcp/capability.ts`), still read
from the project.

![D4: how a project's MCP servers reach the worker that works the item. Chosen: the coding run reads them from its own project when it starts. Instead of: the coordinator attaches them when it hands work over. It comes down to the first row, which runs get them: every coding run for the project, against only runs a coordinator handed over. Second row, the price: the harness gains a per-run MCP option. Third row: no dependency on dispatchTask, against waiting for it. Locks in MCP servers as a project setting, chosen by host alias, with no URL or credential on the row. Flips if a worker that doesn't code needs Linear for the goal](figures/d4-read-at-run-start.svg)
![D4: how a project's MCP servers reach the worker that works the item. Chosen: the coding run reads them from its own project when it starts. Instead of: the coordinator attaches them when it hands work over. It comes down to the first row, which runs get them: every coding run for the project, against only runs a coordinator handed over. Second row, the price: FSD holds the connection per run and the harness gains a tools-only option. Third row: no dependency on dispatchTask, against waiting for it. Locks in MCP servers as a project setting, chosen by host alias, with no URL or credential on the row. Flips if a worker that doesn't code needs Linear for the goal](figures/d4-read-at-run-start.svg)

It comes down to which runs get them: a run started from Inbox never passes through a
coordinator's hand-over.
Expand Down Expand Up @@ -135,8 +135,8 @@ Every rule has one owner. Read a row to see where it is built and where it is on

The handover's binding points are rules now: the layer boundary is
[ER-9](BUSINESS-RULES.md#what-no-child-may-do); both projects shared, on one remote, told apart
by their briefs, is [ER-1](BUSINESS-RULES.md#what-a-person-gets-and-what-they-dont); the Linear
credential variable is [ER-6](BUSINESS-RULES.md#what-a-person-gets-and-what-they-dont); no
by their briefs, is [ER-1](BUSINESS-RULES.md#what-a-person-gets-and-what-they-dont); each person's
Linear key is [ER-6](BUSINESS-RULES.md#what-a-person-gets-and-what-they-dont); no
picker is [ER-15](BUSINESS-RULES.md#what-no-child-may-do); "worker", never "seat", is
[ER-16](BUSINESS-RULES.md#what-no-child-may-do). Review round 1 (Cursor, Codex) settled:

Expand All @@ -145,10 +145,19 @@ picker is [ER-15](BUSINESS-RULES.md#what-no-child-may-do); "worker", never "seat
- **FIX-1905 is one PR, after FIX-1904**, not two stacked PRs ([D1](#d1), [PLAN](PLAN.md)).
- **The checkout mapping is bound to project ids** in the operator's host config, never resolved
from a row's remote alone ([D3](#d3), [ER-13](BUSINESS-RULES.md#what-no-child-may-do)).
- **A row names an MCP server by host-approved alias only**; endpoint and credential variable are
host config ([D4](#d4), [ER-14](BUSINESS-RULES.md#what-no-child-may-do)).
- **A missing `LINEAR_MCP_API_KEY` is a degraded run, not a pass**: the closure's leg a must FAIL
- **A row names an MCP server by host-approved alias only**; the endpoint is host config
([D4](#d4), [ER-14](BUSINESS-RULES.md#what-no-child-may-do)).
- **A missing key is a degraded run, not a pass**: with no key on Settings and
`LINEAR_MCP_API_KEY` unset, the closure's leg a must FAIL
([ER-7](BUSINESS-RULES.md#what-a-person-gets-and-what-they-dont)).

After merge, the owner decided on FIX-1905's spec review
([#3174](https://github.com/fixpoint-labs/flow-state-dev/pull/3174#issuecomment-6131359139)):

- **FSD holds the MCP connection and the key, not the coding agent.** The run gets tools only,
through `mcpTools` ([ER-6](BUSINESS-RULES.md#what-a-person-gets-and-what-they-dont), [ER-9](BUSINESS-RULES.md#what-no-child-may-do)).
- **Each person sets their own key on Settings**; there are no admins. `LINEAR_MCP_API_KEY` only
seeds the operator identity for headless runs ([ER-6](BUSINESS-RULES.md#what-a-person-gets-and-what-they-dont)).
- **Q1 is whether to keep the goal**, not a default inside it; merging accepts the
recommendation unless the owner says otherwise ([Q1](#q1)).
- **A run's branch is reviewed in its worktree** or diffed from the checkout; normal git refuses
Expand Down
31 changes: 17 additions & 14 deletions specs/epics/FIX-1903/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,11 @@ Replaces the section's first paragraph, which says `dev` runs the `devteam` prof
>
> The coding agent is Claude Code. Sign in to Claude Code, or set `ANTHROPIC_API_KEY`, before
> you start; without either, the Lab refuses to start and says so. To run the scripted coder
> instead, which writes one file and costs nothing, set `DEVFORCE_LAB_HARNESS=stub`. Set
> `LINEAR_MCP_API_KEY` to a Linear API key and every coding run on either project can read and
> update Linear. Without it the Lab starts, says Linear is off, and runs work without it.
> instead, which writes one file and costs nothing, set `DEVFORCE_LAB_HARNESS=stub`. Open
> **Settings** and paste a Linear API key, and every coding run you ask for on either project
> can read and update Linear, as you. Each person sets their own. A run for someone who hasn't
> set one works without Linear and says so. For runs with nobody at the keyboard, such as CI,
> `LINEAR_MCP_API_KEY` stands in for the Lab's own user until that user sets a key.
>
> `--dev` serves Shift Manager's pages from source, so a change to a screen shows as you save
> it. `start` runs the same profile on the built pages, and builds them first when they're
Expand All @@ -39,24 +41,25 @@ A new subsection after "Coding work in a project".

> ### Tools a project's coding work gets
>
> A project can name MCP servers, and every coding run for the project gets them: a tracker,
> a docs search, anything the agent should reach while it works. The server running your
> workers decides which MCP servers exist: its config gives each one a name, its address, and
> the environment variable that holds its credential. A project picks from those names:
> A project can name MCP servers, and every coding run for the project gets their tools: a
> tracker, a docs search, anything the agent should reach while it works. The server running
> your workers decides which MCP servers exist: its config gives each one a name and its
> address. A project picks from those names:
>
> ```ts
> // the server's config
> mcpServers: { linear: { url: "https://mcp.linear.app/mcp", credentialEnv: "LINEAR_MCP_API_KEY" } }
> mcpServers: { linear: { url: "https://mcp.linear.app/mcp" } }
>
> // a project
> { id: "fsd", title: "FSD", repository: "https://github.com/acme/fsd.git", mcpServers: ["linear"] }
> ```
>
> A project can't name an address or a variable, and a name the server doesn't know is refused
> when the project is saved. The value goes to the MCP connection only: the agent's shell never
> sees it.
> If the variable isn't set, the server says so when it starts, and each run that misses the
> server says so too; the run still goes ahead without it.
> A project can't name an address or a key, and a name the server doesn't know is refused when
> the project is saved. Each person sets their own key for a server, on Shift Manager's Settings
> page, and a run uses the key of the person it works for. The server holds the connection and
> hands the agent the tools, not the key or the address. A run without a sandbox runs as the same
> operating-system user as the server, so it could read the server's store.
> If the person has no key, the run goes ahead without the server, and its session says so.

The field and option names above are illustrative; FIX-1905's spec pins them. The review sentence in the first draft holds unless FIX-1906 detaches a settled run's branch, which is its choice.

Expand All @@ -66,7 +69,7 @@ The field and option names above are illustrative; FIX-1905's spec pins them. Th
|---|---|---|
| "Working on Shift Manager itself", above, and the same paragraph in `packages/shift-manager/README.md` | FIX-1904, Linear sentences added by FIX-1905 | This document |
| "The `devteam` profile" section: what it is for now (the goal Lab), and that it is opened with `--config` | FIX-1904 | Its `DOCS.md` |
| "Tools a project's coding work gets", above, and the Claude Code harness's MCP option in `packages/claude-code/README.md` | FIX-1905 | Its `DOCS.md` |
| "Tools a project's coding work gets", above; the Claude Code harness's `mcpTools` option in `packages/claude-code/README.md`; the Settings page, in `apps/docs/docs/shift-manager/` | FIX-1905 | Its `DOCS.md` |
| A checkout on the host's machine: how a host maps a remote to it, where branches land, in `projects.md` and `packages/workspace/README.md` | FIX-1906 | Its `DOCS.md` |

Publish each specific with its implementation. The shared paragraph waits until the behaviour it
Expand Down
3 changes: 2 additions & 1 deletion specs/epics/FIX-1903/EVOLUTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,9 @@ Only lineage that spans children. Each child records its own specifics.
| A repository project's run keeps the project's files in `project/` beside `checkout/`, never inside; FIX-1762 BR-28 | **Retained**, and extended to a local checkout | The local-repository mode in `packages/workspace/src/local-host.ts` refuses kept files beside the checkout today ("a source may not name kept files beside it") | ER-3; FIX-1906 owns | A fixed `sourceRepo` app (FIX-1762 BR-22) keeps today's behaviour |
| DevTeam's profile is what `shift-manager start` and `dev` open with no `--config`; `packages/shift-manager/scripts/checkout.mts` | **Amended** | D2: five goal checks need DevTeam unedited, and a dev Lab needs only the two dev projects | The dev profile is the default; DevTeam by `--config`; FIX-1904 owns | Any script that relied on the default passes `--config` with DevTeam's file |
| A served Lab never falls back to the scripted coder silently; `packages/shift-manager/teams/devteam/harness.mts`, `selectHarness` | **Retained** | Q1's recommendation keeps it: no credential refuses the start | ER-2; FIX-1904 owns | DevTeam's default stays the scripted coder |
| The Claude Code harness takes no MCP option, so a conductor-owned ask tool was refused as widening the framework; `packages/harness-manager/src/ask.ts` header, citing LAB-138's decision 3 (an incubation lab; no retained source) | **Amended** for MCP, retained for the ask | D4 adds a generic per-run MCP pass-through, which the Agent SDK already supports. It is not a conductor-owned tool, and the ask stays a file | ER-9; FIX-1905 owns; its spec rechecks the lab decision | Absent option means no servers, as today |
| The Claude Code harness takes no MCP option, so a conductor-owned ask tool was refused as widening the framework; `packages/harness-manager/src/ask.ts` header, citing LAB-138's decision 3 ([LAB-138's spec](https://linear.app/fixpoint-labs/document/lab-138-the-harness-manager-implementation-spec-8444a9f240f9), §6 item 3; [#1437](https://github.com/fixpoint-labs/flow-state-dev/pull/1437)) | **Amended** for MCP, retained for the ask | D4 adds one generic tools-only option, `mcpTools`, which the Agent SDK's in-process servers already support. It is not a conductor-owned tool, and the ask stays a file | ER-9; FIX-1905 owns; its spec rechecks the lab decision | Absent option means no servers, as today |
| A project's coding work was to get MCP servers from the coordinator that hands it over; FIX-1903's and FIX-1905's Linear descriptions | **Superseded** | A run started from Inbox or by the chief of staff passes through no coordinator; the run's own task row names its project on every path | D4, ER-5, ER-8 | Nothing built yet |
| This epic as merged in [#3164](https://github.com/fixpoint-labs/flow-state-dev/pull/3164): the key came from a host credential variable, and the harness got per-run MCP servers (D4's *Locks in*, ER-6, ER-7, ER-9) | **Superseded** by the owner on FIX-1905's spec review, [#3174](https://github.com/fixpoint-labs/flow-state-dev/pull/3174#issuecomment-6131359139): "D2 can't be through Claude … provide a settings page which allows keys to be configured" | FSD must control the connection and the key whichever harness runs; there is no admin, so each person sets their own key | D4, ER-6, ER-7, ER-9 as amended; [FIX-1905's evolution](../../issues/FIX-1905/EVOLUTION.md) lists each statement; FIX-1905 owns | Nothing built. `LINEAR_MCP_API_KEY` stays as the operator's headless seed. Row aliases and host-config endpoints (ER-14) unchanged |

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 row points at specs/issues/FIX-1905/EVOLUTION.md, which isn't on this branch while the epic amendment is already detailed. Either include FIX-1905's retained spec in the same merge window or add an explicit pointer in epic SPEC to whichever PR is canonical (#3174?).


Nothing from [FIX-1870](../FIX-1870/SPEC.md) is changed: its hand-over tools are left alone
(ER-8). Re-check the cited intentions against current code before implementing.
Loading
Loading