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
80 changes: 80 additions & 0 deletions specs/issues/FIX-1795/BUSINESS-RULES.md
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.
153 changes: 153 additions & 0 deletions specs/issues/FIX-1795/DECISIONS.md
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 |

![D1: how a user takes a template update. Replace the copy's configuration, keeping the worker's memory and sessions, chosen, beside adding the new version as a second worker. Decides it: what the worker remembers. Price: the user's own edits to the copy are replaced. Locks in one worker per copy, edits warned and replaced. Flips if users mostly edit their copies](figures/d1-take-update.svg)

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.

![Q1: who can change or remove a published template? Only its publisher, recommended, beside any member. Decides it: whose words a copy is told changed. Price: templates nobody can tidy after their publisher leaves. Locks in the owner rule FIX-1793 builds, nothing of the library's own. Flips if orgs curate the library like a wiki](figures/open-who-changes.svg)

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.

![Q2: how does a user learn an update exists? A mark on the copy in their roster, recommended, beside a message from their chief of staff. Decides it: what new machinery it needs. Price: reaches only a user who opens their roster. Locks in one field every view reads. Flips if templates change for security reasons](figures/open-update-notice.svg)

It comes down to new machinery: a mark is one field, a message is a coordinator change.

## Decided, not asked
Comment thread
jhoffner marked this conversation as resolved.
Resolved

- **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.
Loading
Loading