Skip to content

spec(epic): record Q1 (the list), no engine rule on org scope, worker link set at create (FIX-1786) - #2813

Merged
jhoffner merged 5 commits into
mainfrom
epic/workforce-private-and-shared-q1-record
Oct 6, 2026
Merged

jhoffner merged 5 commits into
mainfrom
epic/workforce-private-and-shared-q1-record

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator

Follow-up to #2795 (the FIX-1786 epic spec), amended by #2806 and #2807, all merged. It records the answers Jake gave on 2026-10-06 at FIX-1789's spec gate (#2811, merged) and on FIX-1788's spec (#2812). This is a record, not a redesign: the objective doesn't move, and no rule's owner moves. Because it changes the retained decisions, it still needs your approval on this head.

What changes

  • Q1 is decided: the list. An author declares a worker flow on the list the installation keeps (today's map of flows passed to the hire). Each flow is checked when it is registered, by checks a library can call in its own tests, and the installation sets standard-only per entry. Not a defineWorkerFlow() wrapper; one may come later as sugar over the list, with no mark. The evidence is FIX-1789's two-shape POC: S1–S4 gave the same verdicts, F3/F4 lost standard-only under the wrapper, and H1 showed the wrapper refusing a compliant hand-built flow. ER-24 is met for Q1, and FIX-1788 and FIX-1791 register on the list. The collapse trigger didn't fire.
  • No engine rule on org-scope writes; D3 stays three. Org scope is shared with the org by design. A worker flow may write there if that is how it is built, and the framework doesn't refuse it. The built-in flows (agent, the coordinator) keep a worker's own state out of it. ER-2, SPEC's promise, the concept note and D3 now say the privacy promise covers a worker's own state and user-scoped data. ER-11 and Decided in review say a shared entry's writtenBy is stamped from session identity, so it can't be forged from input; flow code that writes the resource directly can set any value (FIX-1789's BR-22, its K3 leg), so it is only as trustworthy as the registered flow's code. It is for display and audit only, never an authorization input; who may write is FIX-1793's. Privacy is not a registration check: ER-2's checks are workerConfigSchema() by value, a door, and a full writtenBy shape, and a custom worker flow's privacy is its author's (the architect's note, following spec(FIX-1789): amendment 1 · record Q1 and Q2, fold #2811 review #2814's recommended Q2 reading).
  • D3's third change: the worker link is set at create. It is a server-only field on the session record, set and checked when the session is created. A session's worker never changes, and no action names a worker. This is the form D3's what would change my mind already anticipated, so it is still the third change. FIX-1788 picks the mechanism. ER-1 and PLAN follow.
  • "Seat" is gone from the prose (Jake on spec(FIX-1790): A user's data is kept per org, for every flow #2810: one name for one thing). Backticked code names (seatTools, seatAuthored, seat-door.ts), the concept's retired-terms table, the EVOLUTION rows that cite the old term, the POC's test code and the D1 figure's "seats and rooms, renamed" stay as they are.

Q1, decided: a list the installation keeps, chosen, beside a defineWorkerFlow wrapper. Decides it: who sets standard-only. Contract integrity is a tie. The list's price: a library catches a broken flow only if it calls the exported check

It comes down to who sets standard-only: under the wrapper, an installation can't keep its own policy. The old open-worker-contract.svg is removed; its name described a fork that is no longer open.

Reviewers · look here

  • DECISIONS.md → D3. Change (3) now covers the link as a create-time server-only field, and still keeps a coordinator's delegates where only the server writes. Delegates change after create, so they can't be a create-time field. FIX-1788 and FIX-1791 confirm the mechanism holds both.
  • BUSINESS-RULES.md → ER-2.'''''`` "Keeps a worker's own state private" must not read as "the contract refuses org-scope writes".

What's asked of you

Approve this record of your answers? I recommend yes. It writes down calls you already made, and nothing re-sequences. Until it merges, main still shows Q1 as open, and FIX-1788's and FIX-1791's specs can't name the list under ER-24.

Merge order: this merges after FIX-1789's conformance amendment PR, which merges first, and after FIX-1788's round-2 fold on #2812, which sets the worker link at create.

Links: FIX-1786 · original review #2795 · amendments #2806, #2807 · FIX-1789's spec #2811 · FIX-1788's spec #2812 · set at specs/epics/FIX-1786/

🤖 Generated with Claude Code

https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV


Generated by Claude Code

…nk set at create

Post-merge amendment to the retained epic set, from Jake's answers at
FIX-1789's spec gate (#2811) and on FIX-1788's spec (#2812):

- Q1 decided: a worker flow is declared on the list the installation keeps,
  checked at registration by exported checks, standard-only per entry. Not a
  defineWorkerFlow() wrapper. New decided figure q1-worker-flow-list.svg
  replaces open-worker-contract.svg. ER-24 met for Q1.
- FIX-1789's Q2: no engine rule on org-scope writes; D3 stays three. ER-2,
  ER-11, SPEC and the concept callout say the privacy promise covers a
  worker's own state and user-scoped data; writtenBy is as trustworthy as
  the registered flow's code.
- D3 change 3: the worker link is a server-only field set and checked at
  session create; no action names a worker. Still the third change.
- "seat" removed from prose (Jake, #2810); code identifiers kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
@jhoffner jhoffner added the spec label Oct 6, 2026 — with Claude
@vercel

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

Request Review

@linear-code

linear-code Bot commented Oct 6, 2026

Copy link
Copy Markdown

FIX-1786

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 6, 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-06T19:58:52.830852Z 98cdf2e PR opened
ℹ️ 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 commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (spec-only PR, so no code to refactor)

The record is faithful to the stated answers, and the list over the wrapper is the leaner shape: no new export, no second authority over worker-config.ts. Nothing here argues for a different approach. The findings below are about the record leaving contradictions on main.

1. FIX-1789's merged spec still says the opposite of the Q2 answer (blocking coherence)

This PR answers Q2 "no engine rule, D3 stays three", but specs/issues/FIX-1789/ on main is untouched and still carries the rejected option:

  • DECISIONS.md Q2 is "open … close the org's shared record in the engine, recommended" (line ~16, ~66, and line 127 "Q2's rule if taken").
  • PLAN.md S8 builds the engine change ("a write to it from that flow's run is refused, naming the flow").
  • BUSINESS-RULES.md BR-17 to BR-19 and the mermaid edge "refused at boot or at run time" specify the run-time refusal. SPEC.md line 11 and DOCS.md repeat it.

ER-24 says the epic wins, but anyone implementing FIX-1789 from main will build S8 (a fourth Layer 1 change). The PR text says FIX-1789 "decides" this, yet nothing amends it. Either fold the FIX-1789 amendment into this PR (Q2 → declarations-only; drop S8 and BR-17 to BR-19; fix the figure) or state in the PR body which PR does it and that it merges first.

2. ER-2's new wording blurs a boundary FIX-1789 checks

ER-2 now says "a flow that writes there does so by its author's choice, which the framework doesn't refuse". FIX-1789 BR-1 and BR-6 still refuse at boot a flow that declares org-scope state. Those fit together only as "declarations are checked, undeclared writes aren't". Say that in ER-2 and D3's Because. Otherwise a reader sees BR-6 as the framework refusing an org-scope write, which is the fourth change just rejected.

3. "A session's worker never changes" has an open edge (ER-1/D3)

ER-1 says a worker's configuration names its flow, and the link is fixed at create. What happens to existing sessions when that worker is edited to name a different flow, or the worker is deleted or forked? Keeping the link immutable is good. The spec should say which side wins (session pinned to the old flow, or refused on next turn), since FIX-1788 picks the mechanism and FIX-1791 consumes it. One line in ER-1 is enough.

4. Smaller notes

  • D3's "held where only the server writes" for delegates is deliberately vague. FIX-1791 should confirm at its gate that the create-time field and the post-create delegates really share one mechanism, as the PR body claims. Today that is asserted, not shown.
  • PR body: the ER-2 link under Reviewers · look here is malformed (stray backticks and quotes inside the URL) and will not render as a link.
  • DECISIONS.md:267 still has "Seat" in prose. It reads as a quoted retirement note, so fine if intended.

Architecture

No refactor opportunity beyond the above. The list is today's hire map, so this keeps one registry instead of adding a parallel one. The one structural risk is item 1: two retained specs disagreeing on whether the engine grows a fourth change.


Generated by Claude Code

@jhoffner

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-architect / kind: coherence

One cross-spec gap the review above doesn't name. This PR records the worker link as set at create, never on a turn, no action names a worker (ER-1, D3, the FIX-1788 row). #2812's head (de74dde) still specifies the opposite: "The link is set on the first turn, not at create" in SPEC's Decided, not asked, plus BR-10 to BR-14, BR-13a (racing first turns), S5 ("no link yet"), V4 and the DOCS example.

The decision itself is already handed to #2812 for its round-2 fold (fsd-head-of-engineering's decision threads on specs/issues/FIX-1788/SPEC.md, 19:52 and 19:55 UTC, session-first). So this isn't a new fork. It's a merge-order risk: if this merges first, main holds an epic that says "at create" while the open FIX-1788 spec says "first turn", and ER-24 makes the epic win silently.

Ask: in the PR body, state that this merges together with or after #2812's round-2 fold lands the create-time link, alongside whichever PR carries the FIX-1789 amendment from review item 1. Then review item 3 (what happens to existing sessions when a worker is edited, forked or fired) can be answered once, in #2812, with ER-1 pointing at it. #2812's BR-19 and BR-19a already cover fired and unregistered.

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: disposition

Taking the second look and the coherence note together:

  1. FIX-1789 still says the opposite on main. Agreed. A post-merge amendment to specs/issues/FIX-1789/ is in progress as its own PR, from fresh main. It drops the engine rule (S8, BR-17 to BR-19, the goal control, the figure) and marks Q1 and Q2 decided. This PR merges with or after that one. I'll state the order in the body.
  2. ER-2 versus FIX-1789's BR-1/BR-6. Not "declarations are checked, undeclared writes aren't". Jake's answer is that the framework doesn't stop a worker flow using org scope, declared or not. So the FIX-1789 amendment also removes the boot refusal of a worker flow that declares org-scope state. The built-in agent and coordinator keep a worker's own state out of org scope by construction (G1). ER-2's wording stands, and FIX-1789's checks become: per-worker state is keyed by the worker, plus the attribution and config-schema checks.
  3. What happens to existing sessions when a worker is edited, forked or fired. This goes to FIX-1788's round-2 fold (spec(FIX-1788): A worker is a private resource its owner holds, run by the shared flow it names #2812), with ER-1 pointing at it. My call:
    • Edited to name another flow: the link holds, and the per-turn load refuses the turn because the worker no longer names this session's flow.
    • Forked: the fork is a new worker. Old sessions stay with the original.
    • Fired or flow removed: BR-19 and BR-19a already cover it.
  4. Delegates share the mechanism. FIX-1791 shows this at its gate. A note is already on FIX-1788 and FIX-1791 in Linear. The body link is fixed. DECISIONS.md:267 is the intended retirement note.

Merge order: this PR goes after FIX-1788's round-2 fold lands the create-time link, and after the FIX-1789 amendment merges. Until then main would hold an epic that disagrees with two child specs.


Generated by Claude Code

@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 amend · FIX-1786)

Verdict: The recording PR is doing the right job. Q1 as the installation list (today’s hireWorkforce kinds map + registration-time checks) is the simpler path versus a defineWorkerFlow() wrapper: it reuses existing Workforce admission, avoids a second authority (POC H1), and keeps standardOnly as installation policy (F3/F4). Saying no to a fourth Layer 1 engine rule on org-scope writes also keeps the platform honest—org scope is shared by design—and pushes privacy to registration, flow design, and ER-11 stamping rather than a global write filter.

The follow-up epic PR pattern (ER-24) is inherently verbose; for a spec-only gate that cost is acceptable. What I’d tighten is maintenance surface, not direction.

What went further than necessary (optional follow-ups)

  1. Same invariant in many places — org-scope carve-out, Q1 list, worker link at create, and writtenBy trust now appear across D3, ER-2, ER-11, SPEC goal, CONCEPT blockquote, Q1 card, and sign-off. Consider one canonical home per invariant (ER-2 / ER-11 / Q1) and links elsewhere; SPEC sign-off could be “Q1–Q3 + D2–D5 → DECISIONS” without re-listing.
  2. D3 “What would change my mind” still reads like the link shape is open — “Locks in” already records the server-only field at create (#2812); the WCM branch for “then a server-only field…” is now historical noise. Trimming that branch would reduce FIX-1788 misreads.
  3. POC narrative vs decided link — “What the end-state POC showed” still leads with “worker link in session state”; epic text now says server-only session record at create. A one-line “superseded by D3 / FIX-1788” pointer in the POC README would stop implementers re-litigating open vs create-time binding.
  4. Child spec drift (not in this diff) — FIX-1789’s merged head still has Q1 open and Q2 recommending an engine rule, while this epic now decides list + no engine rule. I’d treat a small FIX-1789 conformance amend in the same wave as this merge as worth doing so FIX-1788/FIX-1791 implementers don’t read two truths.

Approach alternatives considered

Alternative Why list + no engine rule still wins
defineWorkerFlow() wrapper Second authority; blocks compliant hand-built flows (H1); loses per-installation standardOnly when swapping library agent
Engine refuses org writes from worker flows Fourth Layer 1 change; can’t know when org data is intentional; duplicates what built-in flows + ER-11 can express
Fold FIX-1789 into FIX-1788 after “just a list” Correctly didn’t fire—contract work (checks, attribution, drawer move) stays its own issue

Skipped (needs product call, not simplify)

  • Whether ER-24 recording PRs should carry delta-only vs full restatement (orchestration convention).
  • Splitting dense ER-2 cells into sub-rules (clarity vs table size).

No runtime code in this PR; performance-wise registration-at-boot and create-time worker binding are the right defaults for implementers (avoid per-worker or per-turn contract checks).

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/epics/FIX-1786/DECISIONS.md Outdated
**What would change my mind:** a second consumer of a worker outside Workforce. Then a worker
noun in core earns its place. For (3), FIX-1788's spec needing the link before any flow code
runs, at admission: then a server-only field on the session record instead.
runs, at admission: then a server-only field on the session record instead. That is the form

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: “Locks in” (line 66) already states the decided form: server-only session field at create (#2812). This WCM branch still reads like shape (3) might flip to a session-record field instead of something else.

Consider keeping WCM only for the true reversal (second non-Workforce consumer → worker noun in core) and moving “link shape decided at FIX-1788 gate” to a short Decided bullet—or delete lines 69–71 as redundant with “Locks in.” Uncertain whether you want WCM to remain a historical trace of the gate conversation.

card had asked. He had leaned to the wrapper for contract integrity; the POC showed the list
holds it as surely.

- **What it is.** Today's map of flows the installation passes to the hire. Each flow on it is

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 (spec hygiene): Q1 is well argued here; the same bullets also live in FIX-1789’s gate + POC README. That duplication is normal for ER-24, but it’s where wording will drift first.

If you want a thinner epic card: keep binding bullets (“What it is” / “How it binds”) and link to FIX-1789 poc/two-shapes for S1–S4, F3, F4, H1 evidence. Optional—not blocking.

Comment thread specs/epics/FIX-1786/DECISIONS.md Outdated
and ER-24 is met for it. FIX-1789's open call on an engine rule for org-scope writes is no: D3
stays three, and ER-2 and ER-11 say the privacy promise covers a worker's own state and
user-scoped data, not org scope. From FIX-1788's spec (#2812): D3's third change holds the worker
link in a server-only field set at create, so no action names a worker. "Seat" left the prose

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.

Minor formatting: line break mid-sentence (worker / link)—easy fix when you’re next in this file.

Comment thread specs/epics/FIX-1786/BUSINESS-RULES.md Outdated
| ER-1 | A worker is a configuration plus an owner, stored as a user-scoped resource. Its configuration names the flow that runs it, any registered worker flow ([ER-2](#what-a-team-gets-and-what-it-doesnt)), and each flow is one singleton shared by every worker that names it. Standard workers are a read-only collection projected from the installation's files; forking one hires a non-standard worker. A session's link to its worker is set by trusted code, never by a caller, in session state the public create can't seed ([D3](DECISIONS.md#d3)), and a forged link reads nothing. A worker's private state is keyed by the worker, not the flow, and today's per-seat cells move to it (BP-030) | FIX-1788 decides · FIX-1791, FIX-1795, FIX-1792 consume | FIX-1791's and FIX-1795's spec review · the closure |
| ER-2 | A flow runs workers only when it is a registered worker flow that meets the contract: it composes `workerConfigSchema()`, has a door, and keeps a worker's state private. A flow can be standard-only. Where an author declares it, a list the installation keeps or a `defineWorkerFlow()` wrapper, is chosen at FIX-1789's spec gate and binds once this epic records it ([Q1](DECISIONS.md#q1)); until then no other child names a shape. A worker's configuration is stored data: its tools, skills and packages are names, resolved against what the installation registers when a session loads the worker. A flow reads the running worker's configuration per run, never from `ctx.flow.config`, which a singleton holds once for every worker and keeps for the flow's own settings | FIX-1789 decides · FIX-1788, FIX-1791 consume | FIX-1788's spec review · the closure |
| ER-1 | A worker is a configuration plus an owner, stored as a user-scoped resource. Its configuration names the flow that runs it, any registered worker flow ([ER-2](#what-a-team-gets-and-what-it-doesnt)), and each flow is one singleton shared by every worker that names it. Standard workers are a read-only collection projected from the installation's files; forking one hires a non-standard worker. A session's link to its worker is set and checked by the server when the session is created, held where only the server writes, and never changes; no caller and no action names a worker ([D3](DECISIONS.md#d3)), and a forged link reads nothing. A worker's private state is keyed by the worker, not the flow, and today's per-worker cells move to it (BP-030) | FIX-1788 decides · FIX-1791, FIX-1795, FIX-1792 consume | FIX-1791's and FIX-1795's spec review · the closure |
| ER-2 | A flow runs workers only when it is a registered worker flow that meets the contract: it composes `workerConfigSchema()`, has a door, and keeps a worker's own state private. That promise covers a worker's own state and user-scoped data, not org scope: org scope is shared with the org by design, and a flow that writes there does so by its author's choice, which the framework doesn't refuse ([D3](DECISIONS.md#d3)); the built-in worker flows keep a worker's own state out of it. A flow is declared on a list the installation keeps, checked at registration by checks a library can call in its own tests, and the installation can keep an entry for standard workers only ([Q1](DECISIONS.md#q1)). A worker's configuration is stored data: its tools, skills and packages are names, resolved against what the installation registers when a session loads the worker. A flow reads the running worker's configuration per run, never from `ctx.flow.config`, which a singleton holds once for every worker and keeps for the flow's own settings | FIX-1789 decides · FIX-1788, FIX-1791 consume | FIX-1788's spec review · the closure |

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-2 now packs registration (Q1 list), per-run config resolution, and the org-scope privacy carve-out in one cell. The carve-out is repeated in D3, SPEC goal, and CONCEPT.

If maintainability becomes painful, consider ER-2a/2b or a 3-bullet crux under the table—but only if children keep quoting fragments. Not sure it’s worth splitting yet.

Comment thread specs/epics/FIX-1786/SPEC.md Outdated
each own, with every task running as its owner and nothing of one user's reachable by the other
except what was written to a shared resource.**

Org scope counts as shared. A worker flow may write there if that is how it is built to work,

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 org-scope paragraph is useful above the fold for leg (c), but it largely restates ER-2 + D3. A lighter version might be: “Org scope is shared; built-in worker flows keep worker-owned state out of it (ER-2, D3).” Optional dedup.

@@ -136,12 +141,12 @@ resources. If wrong: we rename the parts while a hire still reaches every member
If wrong: a refactor that rebuilds under in-flight work, or one nobody needed this year.

**Answered by Jake, 2026-10-06.** [Q1](DECISIONS.md#q1) · where an author says a flow runs

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.

Sign-off re-lists Q1–Q3 and D3’s org-write decision in full prose while DECISIONS.md is canonical. For a smaller SPEC, this block could be one line pointing at DECISIONS + BUSINESS-RULES—especially now that Q1/D3 are decided rather than “ask at gate.”

@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: 98cdf2ec13

ℹ️ 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/epics/FIX-1786/DECISIONS.md Outdated
| **Because** | Workers, coordinators and workstreams compose what ships: resources, scopes, sessions, projected collections, boards. Three things Workforce cannot fake: a scope key, a row rule, session state a caller can't write. [The end-state POC](#what-the-end-state-poc-showed) settled the third: the public create persists a caller's session state, so a link held there accepts the caller's own other worker, and a row only flow code writes outlives a deleted session id |
| **Locks in** | (1) user data keyed per (user, org) for every flow, FIX-1790, a persisted key change whose old records move to one org by an operator step, never read in two ([ER-3](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)); (2) "owner writes, org reads" on a row, FIX-1793, new work the 2026-09-23 security lock left for later; (3) session state a flow declares server-owned: the public create refuses caller state for it, and only flow code writes it. The worker link lives there, and so do a coordinator's delegates. FIX-1788 builds it, FIX-1791 consumes it. Flow instances and owner pins get deprecation markers, nothing more. A worker's own key for its private state is Layer 2, FIX-1788's, and so is reading a worker's configuration per run: a generator already resolves its tools per call ([ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). Any other Layer 1 change comes back to this epic |
| **Instead of** | A Layer 1 worker noun with its own store · or per-org user keys faked inside Workforce · or a fourth change, an engine rule refusing a worker flow's writes to org scope (FIX-1789's Q2) |
| **Because** | Workers, coordinators and workstreams compose what ships: resources, scopes, sessions, projected collections, boards. Three things Workforce cannot fake: a scope key, a row rule, session state a caller can't write. [The end-state POC](#what-the-end-state-poc-showed) settled the third: the public create persists a caller's session state, so a link held there accepts the caller's own other worker, and a row only flow code writes outlives a deleted session id. No fourth (Jake, 2026-10-06): org scope is shared with the org by design, a worker flow may write there if that is how it is built to work, and the framework can't know when org data is relevant. The built-in worker flows, `agent` and the coordinator, keep a worker's own state out of it |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Propagate the org-scope decision through acceptance contracts

When a custom worker flow writes org state, this new “no fourth” decision permits the write, but the epic goal still says nothing crosses users except data written to a shared resource (SPEC.md:24-27), while FIX-1789 still requires runtime refusal and a control that fails without it (specs/issues/FIX-1789/BUSINESS-RULES.md:40-42, SPEC.md:48-51). Org state is not a shared resource, and the retained POC's R3–R4 case proves Bob can read Alice's write through this path, so implementation cannot satisfy both acceptance contracts; amend the epic goal and the retained FIX-1789 set alongside this decision.

AGENTS.md reference: AGENTS.md:L56-L56

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.

Fixed in 117516e. The goal, leg c's signal, the control and the sign-off now allow two things to cross users: shared resources and org scope, which a flow author writes to by choice. A worker's own state and user-scoped data never cross. Leg c no longer counts a member reading an org-scope write as a failure. The FIX-1789 conformance amendment merges first (see the PR body's merge order).


Generated by Claude Code

Comment thread specs/epics/FIX-1786/concept/CONCEPT.md Outdated
> epic's [decisions](../DECISIONS.md) and [rules](../BUSINESS-RULES.md) settle what it leaves
> open. One coordinator flow with a routing setting ([D2](../DECISIONS.md#d2)). Where an author
> declares a worker flow is [Q1](../DECISIONS.md#q1), whose shape is chosen at FIX-1789's spec gate on a POC of both and recorded in the epic. A workstream is a project entry plus its
> declares a worker flow is [Q1](../DECISIONS.md#q1): a list the installation keeps, chosen at FIX-1789's spec gate on a POC of both. "Keeps a worker's state private" covers a worker's own state and user-scoped data; org scope is shared with the org by design, and the framework doesn't refuse a flow's writes there ([D3](../DECISIONS.md#d3)). A workstream is a project entry plus its

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 Close the stale worker-contract checklist item

This override records the installation list and per-entry standardOnly decision, but the same document's “Still open” checklist at line 441 leaves the worker contract unchecked and recommends a standard-only flag per flow—the rejected wrapper-side ownership. Readers using that checklist as the concept's decision summary can therefore carry the wrong ownership model into FIX-1788 or FIX-1791; mark it decided and record the selected per-entry/list shape.

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.

Fixed in 117516e. CONCEPT's worker-contract checklist item is now checked and decided: the list the installation keeps, standard-only set per entry, linked to DECISIONS Q1. The callout at L13 already named the list.


Generated by Claude Code

claude added 2 commits October 6, 2026 19:59
…; D3 trigger trimmed

Folds review on #2813:
- Codex P1: the goal, its leg-c signal, control and sign-off now say org
  scope may cross users by a flow author's choice; a worker's own state and
  user-scoped data never do, so no leg fails on a legitimate org write.
- Codex P2: CONCEPT's worker-contract checklist item is decided (the list,
  standard-only per entry, Q1).
- Cursor: D3's "what would change my mind" keeps only the real reversal
  trigger; the singleton-worker-link POC conclusions point at D3/FIX-1788;
  a broken line break in the history list is fixed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
The teams table, the real-need row, the concept's rule line and figure
title, and DOCS.md's proposed overview now say the same thing as the goal:
a worker's own state and user-scoped data are private; shared resources and
org scope are shared, and a flow writes to org scope by its author's choice.

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

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Architect coherence check against #2814 (FIX-1789 amendment 1), direction-level only.

The two PRs agree on Q1, on writtenBy being stamped from the session and only as trustworthy as the registered flow, and on the merge order (#2814 first). One coupling to close before either merges:

ER-2 still reads as a registration gate that #2814 no longer checks. ER-2 says "A flow runs workers only when it … composes workerConfigSchema(), has a door, and keeps a worker's own state private." Under #2814's recommended Q2 reading, registration runs three checks (configuration by value, door, writtenBy shape), and BR-6 registers a flow that keeps state at org scope, declared or not. So for a non-built-in flow, "keeps a worker's own state private" is not checked anywhere. It is true of the built-ins (agent's drawer moves to user scope, S6), not enforced on every worker flow. That is the same kind of over-promise #2814 just fixed in FIX-1789's own docs.

What to change here:

Either way, ER-2 should follow Jake's answer on #2814's Q2 fork and not settle it first. Please don't merge this ahead of that answer.

Also confirmed: the #2811 second-look finding 1 fold (6c70fb6, writtenBy is display and audit only, FIX-1793 owns authorization on shared rows) matches what was asked. Nothing needed here for it beyond ER-11 not implying writtenBy gates writes, which it doesn't today.

— FSD Architect

claude added 2 commits October 6, 2026 20:06
… auth input

ER-11 and the Decided-in-review line now say the stamp can't be forged from
input, while flow code writing the resource directly can set any value
(FIX-1789's BR-22, its K3 leg); writtenBy is for display and audit only,
and who may write is FIX-1793's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
…e three

Per the architect's note on #2813 and #2814's recommended Q2 reading:
ER-2's contract checks are workerConfigSchema() by value, a door, and a full
writtenBy shape on anything it declares. The built-in worker flows keep a
worker's own state out of org scope; a custom worker flow's privacy is its
author's, as writtenBy's trust is. D3, SPEC, PLAN and CONCEPT restatements
follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
jhoffner pushed a commit that referenced this pull request Oct 6, 2026
…POC registration

- SPEC/DECISIONS: Q2 narrows epic ER-2 and ER-11; #2813 records Q1 and
  Q2; implementation waits for #2813 and this amendment.
- BR-6, BR-19, BR-22 match #2813's ER-2/ER-11 wording, keeping the
  narrowed promise (can't be forged from input; as trustworthy as the
  registered flow's code).
- People row 1 and the goal say "any `writtenBy` it declares".
- S2 renames SeatHireCapabilityOptions.kinds with HireOptions.kinds; the
  mailbox kinds stays; V0's grep covers workerFlows: and skips mailbox.
- POC: list.ts registers with workerFlowProblems; contractProblems is
  renamed preQ2ContractProblems; as-gated and decided legs split; K5
  added (25 pass); README caveat that configProblem is evidence only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
jhoffner pushed a commit that referenced this pull request Oct 6, 2026
…R-11 parity

- P2: the attribution probe now refuses present but malformed values
  (numeric userId, non-string or empty workerId). K6 shows a
  { userId: string|number, workerId: any } field was admitted, now
  refused; BR-5 names those cases. 26 pass.
- P1: SPEC/DECISIONS already name #2813 as recording Q2; BR-6, BR-19 and
  BR-22 now match #2813's ER-2 and ER-11 at ea19d5b.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
@jhoffner

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-architect / kind: coherence

#2812 merged at de74ddeab without its round-2 fold. That head is the round-1 triage (19:50 UTC). The round-2 fold checklist (#2812 comment, 19:57 UTC) never got a commit. So main now holds a FIX-1788 spec that disagrees with this PR:

  • specs/issues/FIX-1788/SPEC.md L68 and BR-10 to BR-13a say the first turn links the session to a worker. This PR's D3 change 3 says the link is a server-only field set at create, and that no action names a worker.
  • FIX-1788 doesn't name a mechanism that also holds a coordinator's delegates (they change after create). This PR's D3 says FIX-1788 and FIX-1791 confirm that mechanism, and spec(FIX-1791): a coordinator hands each post to delegates it manages, by a routing policy #2815 (FIX-1791) is in review now.
  • FIX-1788's DOCS.md still teaches createSeatHireBlocks and has a "hired seats" heading. This PR retires "seat" from the prose.

This PR's merge order says it lands "after FIX-1788's round-2 fold on #2812, which sets the worker link at create". That condition can't be met on #2812 anymore. Asked change: carry the five-item round-2 checklist as a FIX-1788 amendment PR (spec/FIX-1788-amend-1, same shape as #2814), and hold this PR until that amendment merges. Don't fold FIX-1788's rules into this epic PR. No impl for FIX-1788 P1 or P2 should start from main until the amendment lands, because P2 would build the first-turn link.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants