Skip to content

spec(epic): a private team stays where it was built (FIX-1528) - #2103

Merged
jhoffner merged 4 commits into
mainfrom
epic/workforce-plane-isolation
Sep 23, 2026
Merged

jhoffner merged 4 commits into
mainfrom
epic/workforce-plane-isolation

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator
A team that… Before this epic After this epic
hires a private seat for one person Another org could run it with that person's instructions Only that person, in that org, can list, open, run or resume it. Shipped
drains an org board onto hired seats The refusal was inferred from a shared code path, never exercised A drain onto another org's or user's seat is refused. The task ends errored with the refusal, and its claim is released
turns debug endpoints on for many users The debug listing hands Alice's private seat row to Bob Scoped like the normal route
has a person in two orgs Alice's Acme seat stores data in a cell that follows her to Globex Her Acme seat's data stays in Acme

What's in the box: one pin from the hire row fencing seven doors into a hired seat, four shipped and three left; the principal resolver composed in by the app; user planes, portability and org-owned hire cells not built

Every door into a hired seat is fenced by one pin from the hire row. The fence is only as good as the principal the host resolves, which FIX-1503 makes verified by default.

Why now. The explore (#2070) found any org could run another org's hired seat with its instructions. #2091 closed that. Three smaller holes remain, and each makes the closed fence a false promise. Keeping stored data per org is cheap now and a data split later.

The set: most of it has shipped. What's left is one feature and two bugs: the board-drain leg (FIX-1534), the debug listing (FIX-1535), and a private seat's stored data per (org, user) plus the assembled proof (FIX-1538). As of 2026-09-23: 3 done, 1 explore in review, 2 implementing, 1 to spec; the spec records that snapshot and links to live state. Lead measure: fence legs passing on the real path, 7 of 11. The proof checks both halves of the stored-data cell: Alice's Globex seat and Bob's own Acme seat each start without her marker.

The path: shipped lanes done on 22 and 23 September, two bug lanes in flight at the now line, FIX-1538 waiting on this gate, critical path gate to FIX-1538 to wrap

FIX-1538 is the critical path. The bugs only have to land before its goal runs.

Who owns what: seven rules by five issues, each rule with one owner; FIX-1529's pin consumed by every other child

Every rule has one owner. FIX-1538 owns the proof, so it is the only column that reads every row.

Sign off

  1. This epic closes the plane gap for hired seats, and leaves user planes for later. If wrong: we certify a foundation-honesty outcome while a user's own boards and listings are still open. They are unshipped, so nothing leaks today.
  2. Only a hired seat's own data moves to a per-(org, user) cell (D2). The person's other cross-org data stays as it is. If wrong: Alice's seat leaks through a shared bucket, or every user loses cross-org data nobody decided to take.
  3. No proof issue: FIX-1538's goal is the assembled proof (D1). If wrong: the epic wraps on three green PRs without it.

Already decided, not asked: a private team is not portable, and user planes wait for FIX-1486. What would change my mind on 1: evidence that no host runs two orgs or two users per org on one store.

Reviewers · look here

  • Is it three? The two bugs could be one PR, but they touch different doors (drain dispatch vs debug read). Merging them saves nothing and blurs two regression seams.
  • Rules → ER-9. No child re-keys user scope for flows that are not hired seats. If this falls, every app's cross-org user data changes meaning, not one issue's design.
  • Docs. Two published durable-hire limits are already stale after FIX-1529: pin hired seats to the org and user that hired them #2091. DOCS.md replaces them.

Not here: any single issue's approach. Those are the issue PRs.

Spec · Decisions · Rules · Plan · Docs · Evolution
· Linear FIX-1528 · Project: Workforce: Layer 2 Abstraction (#1818) · merges after human approval and required checks

How to review this — an epic-spec, not an implementation plan

This is an epic-spec: the shared objective and cross-cutting decisions for a set of
issues, in a retained document set. It is not any one issue's implementation design.

In scope to challenge:

  • The objective — is this body of work worth doing, and is the outcome the right one?
  • Whether the set overbuilds. Each issue can earn its place while the whole is too much.
    That question can only be asked here.
  • A cross-cutting decision in DECISIONS.md — shared surface, naming, sequencing, contracts.
  • A rule in BUSINESS-RULES.md with no owner, or two.
  • A missing issue the objective implies, or one in the set that doesn't serve it.
  • Shared promises and publication ownership in DOCS.md; missing or misleading
    predecessor treatment in conditional EVOLUTION.md.

Out of scope — owned by the individual issue specs:

  • Any single issue's approach, architecture, file layout, or test plan.
  • Anything that touches exactly one issue. It belongs on that issue's spec PR.
  • The figures, at the pixel level, and routine status movement since the dated snapshot.
  • POC production polish. End-state experiments under the owning spec's poc/
    show shape and scoping, not shippable implementation. Directional evidence, experimental
    isolation and absence of secrets/generated dependencies remain in scope.

Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.

Required repository checks, approvals and review-thread policy still govern merge.
Optional comments are triaged, not a reason to grind to zero or restart the design review.

🤖 Generated with Claude Code

https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D


Generated by Claude Code

… where it was built

Retained epic spec: the remaining set (FIX-1534, FIX-1535 bugs; FIX-1538
per-(org, user) private cell and the assembled proof), the shipped history
(FIX-1529, FIX-1525/1526), cross-cutting decisions D1-D4, rules ER-1..ER-16,
the path, the shared durable-hire docs draft, and cross-child lineage.

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

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

Request Review

@linear-code

linear-code Bot commented Sep 23, 2026

Copy link
Copy Markdown

FIX-1528

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 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-09-23T21:14:10.114145Z f41f5d4 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 jhoffner left a comment

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.

FSD Architect — coherence / two-direction stamp. Not owner approval / not the merge gate. Shared login looks like Jake; this is approach + Layer-1 fences only.

Lean: yes on the three sign-offs

  1. Hired-seat plane gap only; user planes later (D4). Matches the locked three-plane split: (1) person’s cross-org bag, (2) org-bound, (3) hire-instance private resources. This epic owns plane 3 (and the admission/read doors into hired seats). Certifying foundation honesty while user boards/listings stay open is the honest trade — they are unshipped, and teaching them before FIX-1486 soft-mixes names into listable surfaces. Keep D4.

  2. D2 / ER-9 — only a hired seat’s own data moves to a per-(org, user) cell. Correct Layer-1 fence. Re-keying bare user scope for every flow would silently decide plane 1. Second hire store / UserWorkforce / Hire|Role|Agent|Team|Channel as L1 stay invent-killed (ER-6). Narrow change to where a pinned instance resolves user-scoped data is the right size.

  3. D1 — FIX-1538 owns the assembled proof; no fourth proof issue. Matches board nest (1538 critical path; 1534/1535 separate doors). “Is it three?” — keep three. Drain admission vs debug read are different regression seams; folding them blurs fail-closed evidence.

Also locked / already decided (do not reopen here)

  • Private team not portable; user planes wait FIX-1486.
  • FIX-1534 / FIX-1535 implement ahead of this gate (owner-authorized); review on their PRs.
  • ER-11: do not re-parent FIX-1486 / 1396 / 1503 / 1442 / 1536, or reopen F2 (#2091) acceptance.
  • Sibling #2070 stays the explore record, not a competing epic.

Soft notes (not blockers)

  • Epic title reuses the product phrase FIX-1538 owns as a child — fine if body keeps seat / hired instance as the noun (it mostly does). Avoid teaching “team” as an L1 type.
  • Lead measure 7/10 + ER-13 real-path proof is the right honesty bar after the drain leg went unproven on shared-code-path inference.
  • Docs debt after #2091 called out in DOCS.md — good; don’t let durable-hire publish contradict the pin.

No product fork vs locked planes / F2 / #2091 / FIX-1538. No D-n. Spec may merge when Jake owns it.

— FSD Architect

Copy link
Copy Markdown
Collaborator Author

from: epic-lifecycle
session: epic/FIX-1528
kind: block

Red CI on f41f5d4 doesn't come from this PR. Storybook Build, Kitchen-sink E2E (Playwright), and Typecheck & Test all fail at the shared Turbo build, before any test runs. The error is TS2339: Property 'manifest' does not exist on type 'RowProblem | { manifest: WorkerManifest }' in packages/workforce/src/manifest-sources.ts and seat-hire-capability.ts.

main has been red since ffe2b6e, where #2091 and #2079 collided. This PR only adds specs/epics/FIX-1528/. The same failure shows up on #2070, #2080 and #2094.

Fix: db41f92 on #2094, not merged yet. It isn't ported here because this is a spec-only PR and it can't merge before owner approval anyway. CI will run again on the next push once #2094 lands. No re-run spent here: while main stays broken it would fail the same way.


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 epic, not implementation)

Reviewed the retained set under specs/epics/FIX-1528/ with the /simplify lens: parallel read-only passes on documentation shape, process cost, and reuse vs alternatives (#2070 explore, scope-keys.ts, goals/hire-plane/).

Did the approach go too far?

On engineering direction: no. The epic correctly narrows what #2070 opened:

  • D2 (pinned-only user cell at the engine seam) is the smaller fix than re-keying user scope for every flow or inventing a Workforce-side second store. That matches how scope-keys.ts already splits shared vs isolated keys and where explore pinned the leak (shared bucket / C7).
  • D1 (one feature + two bugs, proof folded into FIX-1538) avoids a fourth proof issue that would restate ER-15, and avoids a single mega-PR across drain, debug routes, migration, and store keying.
  • D3 (framework seam + real-path legs) is the right reaction to the drain leg going unproven on #2091; a softer metric would be simpler on paper but would recreate the false confidence this epic is closing.

The seven-child set looks large, but most rows are history (explore, hire tools, F2). The remaining surface area is three doors — that is proportionate, not scope creep.

Where the artifact could be simpler (optional, not blocking merge)

These are spec-maintenance simplifications; they do not change the objective or the cross-cutting calls I would sign off.

  1. Invent-kills in three places — SPEC.md "Not doing", DECISIONS.md "Decided before", and BUSINESS-RULES.md ER-6–10 largely restate #2070 / Architect fences. Consider one linked cluster (or fewer ER rows) so amenders do not chase three copies.
  2. DECISIONS.md implementation detail — The scope-keys.ts walkunder D2 and the long "Decided before" block are valuable but read like FIX-1538's spec preview. Moving migration/keying evidence to FIX-1538's retained spec would keep the epic coordination doc thinner (template intent: cross-cutting cards only).
  3. figures/path.svg with calendar + "now" — For a mostly-shipped epic, this is the highest-rot figure; mermaid + the dated set table already carry dependencies. FIX-1503 uses the same pattern while nothing is done yet — here, dropping or de-dating the lane chart may be cheaper than redrawing pixels on every phase tick.
  4. DOCS.md full CREATE draft — Epic-level ownership table + REMOVE list may suffice; verbatim durable-hire.md prose can live on FIX-1538's DOCS.md when filed to avoid two canonical drafts.
  5. Minor duplication — ER-13 vs D3, PLAN "not children" vs SPEC + ER-11, ownership figure vs ER owner column. Low cost to readers today; easy trim in a follow-up amendment PR.

Alternatives considered (and why I would not switch)

Alternative Why not (for this epic)
Global (org, user) user scope Decides the person's cross-org plane without a product call (ER-9 / D2)
One bug PR for 1534+1535 Saves tracking; blurs two regression seams the PR body already separates
Separate proof issue Restates FIX-1538's outcome unless 1538 is cut (D1 collapse trigger)
Third-party package for fencing No obvious dependency; admission + roster pin are first-party framework seams

Verdict

Approve the objective and cross-cutting decisions. The implementation approach encoded in D1–D4 is the cleaner change set relative to the explore; remaining simplify wins are editorial on the retained documents, best handled in a small amendment PR if you want less duplication before FIX-1538 specs.

No changeset needed (spec-only).

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/epics/FIX-1528/DECISIONS.md Resolved
Comment thread specs/epics/FIX-1528/BUSINESS-RULES.md Resolved
Comment thread specs/epics/FIX-1528/PLAN.md Resolved
Comment thread specs/epics/FIX-1528/SPEC.md Resolved

Copy link
Copy Markdown
Collaborator Author

from: second-look + improve-codebase-architecture (scheduled review pass)
kind: info

Ran /second-look and considered improve-codebase-architecture. No findings.

/second-look verdict: appropriately scoped. Diff is +655/−0 across 9 files, all under specs/epics/FIX-1528/ (SPEC.md, DECISIONS.md, BUSINESS-RULES.md, PLAN.md, DOCS.md, EVOLUTION.md, 3 figures). The six-document/three-figure shape isn't discretionary — it's mandated by docs/contributing/epic-spec-template.md for any Epic-labeled Linear issue, which FIX-1528 carries. Every section traced back to a documented contract (template requirement, or a decision card that explicitly rejects a larger alternative). All docs land under their template word budgets. Nothing to cut.

improve-codebase-architecture: not applicable. This PR touches zero application code (no packages/*/src, no tests) — it's spec/doc only. The skill's own gate is "only surface refactor opportunities where the PR is a vehicle for one via a real feature/bug/improvement"; there's no code change here to hang a refactor on.

No action needed from a downstream agent on this pass — flagging only so it's clear this review ran and came up clean, not skipped.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01XMuTCxYUfkcSxbFuiKorwK


Generated by Claude Code

jhoffner pushed a commit that referenced this pull request Sep 23, 2026
…ation filed, at its gate

Status-only refresh on an epic-created transition. Re-derived live from
Linear and the epic PRs at 2026-09-23 21:20 UTC: eighth epic row and graph
node for FIX-1528 (3/7, spec #2103 at objective gate); kitchen-sink 4/8 in
flight; W5 3/8 under its Linear title; agent flow 8/11; 150 work issues,
74 unparented. Arc redrawn to Sep 23 with eight lanes. No decisions, rules
or outcome touched.

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

@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: f41f5d4a6a

ℹ️ 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-1528/BUSINESS-RULES.md Resolved
Comment thread specs/epics/FIX-1528/BUSINESS-RULES.md Resolved
Comment thread specs/epics/FIX-1528/DOCS.md Resolved
Comment thread specs/epics/FIX-1528/DOCS.md Resolved
- ER-2: a refused board hand-off ends errored with its claim released,
  refused at the dispatch seam; no pre-claim fence (matches #2106).
- ER-15/ER-4: the proof covers the user half of the (org, user) cell,
  Bob's own Acme seat must not read Alice's marker; lead measure 7 of 11.
- DOCS: drop the user-plane paragraph (ER-9 - ER-10, ER-16); resolver
  warning phrased around the resolved-principal contract so it holds in
  either order relative to FIX-1503.
- Trims: ER-6 - ER-10 clustered into two rows; D2 evidence moves to
  FIX-1538's spec.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D
@jhoffner jhoffner added the spec label Sep 23, 2026
@jhoffner
jhoffner merged commit 5dd3e3a into main Sep 23, 2026
12 checks passed
@jhoffner
jhoffner deleted the epic/workforce-plane-isolation branch September 23, 2026 23:58
jhoffner pushed a commit that referenced this pull request Sep 24, 2026
…d running; W5 retitle folded

Update on FIX-1528's approval (spec #2103 merged 2026-09-23 23:58 UTC,
Linear In Development). Status re-derived live at 2026-09-24 00:01 UTC:
4 done, 3 in flight, 1 not started; FIX-1528 6/8, FIX-1455 6/8, W5 3/8,
agent flow 8/11; 152 work issues, 75 under no epic.

Folded the four items held from the last refresh:
- W5 retitle prose: SPEC's W5 paragraph and PLAN's consumes/releases row
  now describe release QA and its three exit proofs, not living
  assemblies; the decided-once kitchen-sink row cites W5's D9.
- A FIX-1528 consumes/releases row in PLAN, plus a kitchen-sink ->
  plane isolation coordination seam.
- The kitchen-sink -> FIX-1528 edge, confirmed against FIX-1528's merged
  EVOLUTION.md (it retains FIX-1475's org-scoped roster row and adds the
  owner pin); edge label now names FIX-1475.
- BUSINESS-RULES: the backticked FIX-1354 reference is now a link.

Also corrected surfaces still carrying old answers: #1718 closed Sep 22,
FIX-1359 at 8/11, PLAN's "45 unparented". Arc redrawn to Sep 24
(46.5 px/day) and rendered in both themes. Linear project content not
written: the owner locked the mirror on Sep 18.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D
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