Repository navigation
spec(FIX-1795): An org's worker library: templates a user copies onto their own roster #2819
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
01a430c
spec(FIX-1795): an org's worker library, templates a user copies onto…
claude b7c2531
merge main into spec/FIX-1795
claude d485b98
spec(FIX-1795): fold review round 1 · a version keeps its flow, diges…
claude 6e50806
spec(FIX-1795): use FIX-1788's createWorkerHireBlocks in examples
claude 1972e6c
spec(FIX-1795): fold review round 2 · a take is bound to its offer
claude File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| # FIX-1795 · Business rules | ||
|
|
||
| [Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) · [Docs](DOCS.md) | ||
|
|
||
| The cases, written as rules. Alice and Bob are users of org acme; Carol is in org globex. The | ||
| *proved by* column is the check the plan runs. Rules marked Q1 or Q2 are written for the | ||
| recommended answer and move with it. | ||
|
|
||
| ## Publishing | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-1 | Alice publishes a worker of her own | A template in acme's library: the worker's flow, instructions, team instructions, skill, tool, package and document names, the flow's own settings, a name, a description, version 1. It names Alice, and the worker too when a worker published it ([ER-11](../../epics/FIX-1786/BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). Her worker is unchanged | CI · VG leg a | | ||
| | BR-2 | Alice's worker has sessions, memory at any layer, or skills it wrote into its drawer | None of it is in the template. Only names cross. A skill name only her worker's drawer holds fails the save check, so the publish is refused naming it (BR-5): a copy would get the name and not the skill | CI · VG leg a | | ||
| | BR-3 | Alice publishes a standard worker | Refused: every user already has it; fork it, then publish the fork. Nothing written | CI · VG leg c | | ||
| | BR-4 | Alice names a worker that isn't hers | Refused with the same answer as a worker that doesn't exist | CI | | ||
| | BR-5 | Alice's worker no longer passes the checks a save runs (its flow gone or kept for standard workers, its configuration refused) | Refused with that check's reason. Nothing written | CI | | ||
| | BR-6 | Alice and Bob each publish a template called `researcher` | Two templates, two ids from the server. The listing shows who published each | CI | | ||
| | BR-7 | Bob publishes his copy of Alice's template | A new template of Bob's. Alice's is unchanged | CI | | ||
| | BR-8 | A publish finishes a turn | The turn names the library as a collection it wrote, so a view reloads it. No tool name is special-cased ([ER-19](../../epics/FIX-1786/BUSINESS-RULES.md#what-no-child-may-do)) | CI | | ||
|
|
||
| ## The library | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-9 | Any member of acme lists the library | Every template in acme, each with its name, description, flow, version, who published it, and what it grants: its tools, skills, packages, documents and collections. That is what an add offers | CI · VG leg a | | ||
| | BR-10 | Carol lists her library | Nothing from acme. A user in both orgs sees each org's own library | CI · VG leg c | | ||
| | BR-11 | A caller writes a template through the app's resource routes | Not possible: only the library's own actions write templates | CI | | ||
|
|
||
| ## Adding a copy | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-12 | Bob adds Alice's template | A new worker of Bob's from the template's configuration, through [FIX-1788](../FIX-1788/BUSINESS-RULES.md#holding-a-worker)'s hire write and its save check. Its id is the one Bob gives, or the template's name. It records the template and version it came from, and a digest of the configuration as saved. The turn names the roster as written | CI · VG leg a | | ||
| | BR-13 | Bob's copy runs | As Bob, in sessions he finds or starts with `ensureWorkerSession`, linked to it at create (FIX-1788 BR-10), with his own memory. It reads nothing of Alice's | CI · VG leg a | | ||
| | BR-14 | Bob adds the same template twice | Two workers. The second needs an id not on his roster; a taken id is refused, naming it (FIX-1788 BR-4) | CI | | ||
| | BR-15 | The template's flow is no longer registered, is kept for standard workers ([FIX-1789](../FIX-1789/BUSINESS-RULES.md#naming-a-flow) BR-14), or the flow refuses its configuration | Refused at add, naming the template and the reason. Nothing written | CI · VG leg c | | ||
| | BR-16 | The template grants a document or collection its flow doesn't declare | Refused at add, naming it (FIX-1788 BR-6a) | CI | | ||
| | BR-17 | Alice publishes her Codex, Claude and Cursor variants, and Bob adds all three | Three templates, three workers of Bob's. Each carries its own copy of the shared core instructions; none follows another | CI | | ||
| | BR-18 | A hire or an edit supplies a copy record of its own | Not taken from input: only adding and taking an update set it. It is never an access input, and it offers no update from a template the user can't read | CI | | ||
|
|
||
| ## Updates | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-19 | Alice publishes a worker of hers on the template's flow onto her template | Version 2, naming Alice. Bob's copy is unchanged: his next turn runs version 1 | CI · VG leg b | | ||
| | BR-19a | Alice publishes a worker of hers on another flow onto her template | A new template, version 1, and the reply names both flows. The old template and its copies are unchanged. A version never changes a template's flow, so no update can strand a copy's sessions ([FIX-1788](../FIX-1788/BUSINESS-RULES.md#a-sessions-worker) BR-10–13, BR-19b) | CI | | ||
| | BR-20 | Bob lists his roster after that | His copy is marked: version 2 exists, and whether taking it would overwrite edits he made since he took version 1, read from the copy record's digest (Q2) | CI · VG leg b | | ||
| | BR-20a | Bob opens the update before taking it | The offer lists what version 2 grants that his copy doesn't hold: tools, skills, packages, documents and collections. Nothing changes until he takes it | CI | | ||
| | BR-20b | Alice publishes again, or Bob edits his copy, after Bob opened the offer and before he takes it | The take is refused: it carries the version and the copy digest the offer showed, and one of them changed. Bob gets a fresh offer with the current grants and the current warning. Nothing changes. No lock: the take compares and sets on the copy row | CI | | ||
| | BR-21 | Bob takes the update | His copy's configuration becomes version 2, through the same save check. Its id, sessions and memory stay ([D1](DECISIONS.md#d1)), and its sessions keep running: the flow is the same (BR-19a), unless Bob moved his copy to another flow himself (BR-22). His next turn on any of them runs version 2. The mark clears | CI · VG leg b | | ||
| | BR-22 | Bob edited his copy before taking the update | His edits are replaced, and the offer said so beforehand. Nothing merges. If his edit moved the copy to another flow, the take moves it back, and the offer says that too: sessions he started on that flow are refused, and his next `ensureWorkerSession` starts a fresh one (FIX-1788 BR-19b) | CI | | ||
| | BR-23 | Bob never takes it | His copy never changes | CI · VG leg b | | ||
| | BR-24 | Version 2 fails Bob's save check | The take is refused with the reason. His copy is unchanged | CI | | ||
| | BR-25 | Alice fires the worker her template came from | The template and every copy stay as they are. Alice can still remove the template, or publish another worker of hers on its flow onto it | CI | | ||
|
|
||
| ## Changing and removing | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-26 | Alice changes or removes her template | Allowed, under FIX-1793's "owner writes, org reads" rule (Q1) | CI | | ||
| | BR-27 | Bob changes or removes Alice's template, by any path | Refused by that rule (Q1). Who a template names is never what decides ([ER-11](../../epics/FIX-1786/BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)) | CI · VG leg c | | ||
| | BR-28 | Alice removes her template | It leaves the library. Every copy keeps running, and its mark clears. A copy's record still names where it came from | CI | | ||
| | BR-29 | Alice no longer belongs to acme | Her templates stay. Nobody can change or remove them, short of an operator working on the store (Q1's price) | CI | | ||
| | BR-30 | A change or removal finishes a turn | The turn names the library as written | CI | | ||
|
|
||
| ## Failure taxonomy | ||
|
|
||
| A refused publish, add, take or removal changes nothing and says why, naming the template or the | ||
| worker. A copy that its flow later refuses fails at its turn, as any worker does (FIX-1788 | ||
| BR-22); its template is not consulted. Nothing retries, and nothing a user holds changes without | ||
| their action. | ||
|
|
||
| ## Acceptance criteria this issue owns | ||
|
|
||
| [The goal](SPEC.md#the-goal-and-how-well-know-its-met) passes with three users across two orgs, | ||
| after the same run fails under `live-template` and `org-writes`. | ||
| [ER-10](../../epics/FIX-1786/BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt) holds for | ||
| every copy. The closure's leg a ([FIX-1797](https://linear.app/fixpoint-labs/issue/FIX-1797)) | ||
| then copies a template in Shift Manager; that run is FIX-1797's. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,153 @@ | ||
| # FIX-1795 · Decisions | ||
|
|
||
| [Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) | ||
|
|
||
| What the model already decided is the epic's and the concept's, and is not reopened here: a | ||
| template is a non-standard worker's configuration, the library is a shared resource, a copy is a | ||
| snapshot ([ER-10](../../epics/FIX-1786/BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)), | ||
| standard workers stay out. These are the calls about what a user sees when a template moves on, | ||
| and two the Architect asked to be raised rather than picked. | ||
|
|
||
| ## The tree | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| I["FIX-1795"] --> D1["D1 · an update replaces the copy's configuration, keeps memory"] | ||
| D1 -.->|"rejected · memory starts over"| X1["add it again as a new worker"] | ||
| D1 -.->|"rejected · a merge nobody can predict"| X1b["merge the user's edits"] | ||
| I --> Q1["Q1 · open · only the publisher changes or removes"] | ||
| Q1 -.->|"not recommended · anyone rewrites what others add"| X2["any member"] | ||
| Q1 -.->|"not recommended · a new role, new engine work"| X2b["an org admin role"] | ||
| I --> Q2["Q2 · open · a mark on the copy, a warning only when edits would be lost"] | ||
| Q2 -.->|"not recommended · a channel built for one message"| X3["a notification channel"] | ||
| ``` | ||
|
|
||
| Solid edges are what you're signing or asked. Q1 and Q2 are the two open asks. | ||
|
|
||
| <a name="d1"></a> | ||
| ## D1 · Taking an update replaces the copy's configuration, and the worker keeps its id, sessions and memory | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | Adding the new version as a second worker beside the old one · or merging the user's own edits with the template's new version | | ||
| | **Because** | The worker a user has worked with keeps what it learned: its memory and sessions are keyed by the worker ([FIX-1788](../FIX-1788/BUSINESS-RULES.md#what-a-worker-runs-with) BR-23), so a new worker starts with none. A merge of two edited instruction texts is a result neither side wrote. Replacing in place goes through the same save check as a hire, so a taken update can't run what a hire would refuse | | ||
| | **Locks in** | A user who edited their copy loses those edits when they take an update. The offer says so before they take it, only when they did edit it ([Q2](#q2)), and nothing merges. A user who wants both keeps their copy and adds the template again as a second worker | | ||
|
|
||
|  | ||
|
|
||
| It comes down to memory: a second worker starts with none of what the copy learned. | ||
|
|
||
| **What would change my mind:** users who mostly edit their copies after adding them. Then a | ||
| take that replaces edits is the wrong default, and taking an update should add a second worker. | ||
|
|
||
| <a name="q1"></a> | ||
| ## Q1 · open · Who can change or remove a published template? | ||
|
|
||
| **The fork.** Only the user who published it · any member of the org · or an org admin role. | ||
|
|
||
| **In plain terms.** Alice publishes a release-notes writer. Bob finds a typo in its instructions. | ||
| Under *only the publisher*, Bob tells Alice, or publishes his own fixed copy beside hers. Under | ||
| *any member*, Bob fixes it in place, and every copy is told the template changed, with Bob named | ||
| as the writer. If Alice leaves the org, under *only the publisher* her template stays as it is | ||
| until an operator removes it. | ||
|
|
||
| **The trade-off.** *Only the publisher* is the "owner writes, org reads" rule FIX-1793 builds | ||
| for workstreams, so the library adds no access check of its own. Its cost is templates nobody | ||
| can tidy once their publisher is gone. *Any member* keeps a library current, at the price that | ||
| anyone rewrites what the users who added it trusted. An update is never applied on its own, so | ||
| nobody's running worker changes either way. *An org admin* needs a role the framework doesn't | ||
| have: every user is equal inside an org today. | ||
|
|
||
| **My recommendation: only the publisher.** It needs no new rule, it matches who a template | ||
| names, and a teammate with a fix can publish their own. An admin override can come later on | ||
| whatever role the framework adds. | ||
|
|
||
| **What would change my mind:** orgs that expect a shared library to be curated by the team, the | ||
| way a wiki is. Then *any member*, with every change named. | ||
|
|
||
| **If wrong:** the library fills with templates whose publishers have left. Cheap to reverse: | ||
| widening who may write later changes no stored template. | ||
|
|
||
|  | ||
|
|
||
| It comes down to whose words a copy trusts: under *any member*, anyone rewrites them. | ||
|
|
||
| <a name="q2"></a> | ||
| ## Q2 · open · How does a user learn that an update exists? | ||
|
|
||
| **The fork.** A mark on the copy in their own roster · a message from their chief of staff · a | ||
| notification channel built for it. | ||
|
|
||
| **In plain terms.** Alice republishes her template. Under *a mark*, Bob sees "update available" | ||
| on his copy the next time he opens his roster, and nothing tells him sooner. When he opens the | ||
| update, it lists anything the new version can reach that his copy can't, and warns him only if | ||
| taking it would overwrite changes he made to his copy himself. Under *the chief of | ||
| staff*, his chief of staff mentions it in its next conversation with him. Under *a channel*, he | ||
| gets a notification wherever the app sends them. | ||
|
|
||
| **The trade-off.** A mark is data on the roster listing every view reads, so Shift Manager shows | ||
| it as a badge and any later view or coordinator can read the same field. It reaches only a user | ||
| who looks. The edit-aware warning costs one stored fingerprint per copy of what it took. The chief of staff reaches the user sooner, but puts a library concern inside a | ||
| coordinator FIX-1791 is building now, and works only for users who have one. A channel is new | ||
| infrastructure for one message. | ||
|
|
||
| **My recommendation: a mark on the copy, with a warning at the take that appears only when | ||
| the user's own edits would be lost.** It is the smallest thing that keeps the promise, "you can | ||
| be told an update exists", and it invents no channel. The warning is edit-aware so it means | ||
| something when it shows: one shown on every update trains users to click past it. The chief of | ||
| staff can read the mark later without any change here. | ||
|
|
||
| **What would change my mind:** templates that change for security reasons, where a user who | ||
| doesn't open their roster keeps running the old one. Then the chief of staff should say so. | ||
|
|
||
| **If wrong:** users keep stale copies longer. Cheap to reverse: anything that tells a user later | ||
| reads the same mark. | ||
|
|
||
|  | ||
|
|
||
| It comes down to new machinery: a mark is one field, a message is a coordinator change. | ||
|
|
||
| ## Decided, not asked | ||
|
|
||
| - **A new version keeps the template's flow.** A worker on another flow makes a new template | ||
| (BR-19a), so taking an update keeps the copy's sessions running (FIX-1788 BR-10–13, BR-19b), | ||
| unless the user moved the copy to another flow themselves; the offer says so (BR-22). | ||
| - **A take is bound to the offer it was shown.** It carries the offered version and copy digest | ||
| and is refused if either changed, a compare-and-set with no lock (BR-20b): new grants are never | ||
| applied unseen. | ||
| - **The copy record keeps a digest of what it took**, so the take warns only when the user's own | ||
| edits would be lost: one field, against a warning on every update that users learn to ignore. | ||
| - **Model variants are copied, never referenced**, as FIX-1788 | ||
| [D3](../FIX-1788/DECISIONS.md#d3) copies a fork: one rule for every copy a user holds. | ||
| - **The library blocks come from the hire blocks' factory**, so the one save path has one | ||
| construction path. No worker tool publishes in this issue. | ||
| - **Change and removal wait for FIX-1793's owner rule** (epic ER-16); P1 stacks on it. | ||
| - **No predecessor design.** The 2026-10-04 variants lock is the epic's | ||
| [EVOLUTION](../../epics/FIX-1786/EVOLUTION.md#predecessor-designs) row. | ||
|
|
||
| ## Considered and dropped | ||
|
|
||
| | Alternative | Why not | | ||
| |---|---| | ||
| | A copy that follows the template | Anyone who edits the template changes what runs with your access (the concept) | | ||
| | Copy straight from another user's roster | Bob would read Alice's roster: the hole the epic closes | | ||
| | A library-only check of who wrote a template | `writtenBy` is never an access input (ER-11), and the Architect fenced a second ACL | | ||
| | A variant group in the library | Ergonomic only; a template's description can name its variant | | ||
| | A version-only mark and the same warning on every take | A warning that always shows stops being read; the digest is one field | | ||
| | The publishing worker's id stored on the template | Nothing reads it: a new version names its template | | ||
| | A second factory for the library | Two places to pass `workerFlows` and the save check | | ||
|
|
||
| ## How it got here | ||
|
|
||
| - **Draft** — framed as the only way a team shares a private worker: a template is configuration | ||
| published to an org-scoped library, a copy is a hire that never reads the template again, and an | ||
| update is the user's choice; two open asks the Architect flagged; two PRs on FIX-1788 and | ||
| FIX-1793's owner rule. | ||
| - **Review round 1** — aligned to FIX-1788's amendment (sessions linked at create); a version | ||
| keeps its template's flow; the digest kept and pinned; the take offer lists new grants; a | ||
| drawer-only skill name refused at publish; the build sequenced after the MVP. | ||
| - **Review round 2** — a take is bound to the version and copy its offer showed; the cross-flow | ||
| exception to session continuity is stated and warned; the read of older template shapes | ||
| dropped, since the library is new. | ||
|
|
||
| **Open:** Q1, Q2. | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.