Skip to content
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Rules — Framework simplification & cleanup

[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md)

What every epic under this project obeys. Each rule has **exactly one owner**, the epic that
implements and proves it; the others inherit it. A rule with two owners is a seam; a rule with none
is a wish.

| | Rule | Owner | Checked where |
|---|---|---|---|
| **PR-1** | When an epic's docs show how a host is mounted or called over HTTP, then they teach a verified caller; a caller-typed `userId` appears only as the named local-development escape, never as a shipped mode | FIX-1503 | FIX-1503's consumer cutover, over every docs example it names; FIX-1637's own docs review for any page it adds |
| **PR-2** | When an epic removes a published root export, then the release carries it in the one removed-root-exports summary line, with the total count, never a name per export | FIX-2447 | j5 in the adopter-goal check: the line on every run, the exact count on the Version Packages PR only |

**PR-1 is FIX-1503's ER-10, raised to this altitude** because a sibling now writes the pages it
governs: FIX-1637's config matrix covers the host mount for webhooks, cron and event ingress.
Whichever lands second reads the other's pages ([Plan](PLAN.md) → seams).

**PR-2 is owned by a wrapped epic.** Clean SDK built and proved it at closure
([Decisions](DECISIONS.md) → 8); every later epic that drops a root export inherits it and edits no
changeset until release. Folding j5 into the CI checks after release moves to
[FIX-2739](https://linear.app/fixpoint-labs/issue/FIX-2739), under the docs revamp. The repo-wide grounding,
including BP-031 on caller input, binds every epic already and is not restated here.

**No epic may:**

- **Collapse a block kind or a state scope, or deprecate scope state.** Decided once, twice
([Decisions](DECISIONS.md) → 1, 2).
- **Merge the two durable-storage primitives**, or re-derive the rejected splits by scope range or
by persistence (→ 3).
- **Remove capabilities, skills, tools, `ui` or thought-fabric**, or cut the sequencer's public
surface (→ 4, 5).
- **Make client data visible by default** (→ 6).
- **Alias a moved or renamed published export**, or keep it reachable from its old path (→ 7).
- **Drop the install docs' `--allow-build=better-sqlite3` flag** before FIX-2737 lands (→ 9).
- **Add a capability under this project's name.** A cleanup that needs a new feature files it
where features live; this is the fence in the [territory](SPEC.md).
86 changes: 86 additions & 0 deletions spec/_projects/framework-simplification-and-cleanup/DECISIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# Decisions — Framework simplification & cleanup

[Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md)

Calls that bind **more than one epic**. A call that touches one epic belongs to that epic's own
`DECISIONS.md`; absorbing it here would make this a design nobody signed off.

## Cards

None yet. The calls that bind more than one epic so far were each settled once by the owner and
are not live forks, so they sit under *decided once* below; the shared seams are in
[Plan](PLAN.md) and the rules in [Rules](BUSINESS-RULES.md). The first live call a second epic
would otherwise have to make again gets card PD-1.

## Decided once

Answered at project altitude, so a later epic reads the answer instead of re-litigating it. Each
carries where it was settled.

1. **The block kinds are not collapsed.** Four when the review was written, five since the
evaluator joined. The review proposed merging them; the validation pass went to the code and
retracted it. *From the project's original description.*
2. **The state scopes are not collapsed, and scope state is not deprecated.** The review
retracted the collapse. FIX-1157 then tested the narrower version, deprecating session, user
and org state, and abandoned it: request scope keeps the same machinery anyway, so the removal
buys about a third of the prize while deleting the client-facing half. The trial removal of org
state was closed unmerged. *Validation pass; FIX-1157, Aug 20.*
3. **The two durable-storage primitives stay two: symmetry, not merger.** Where scope state and
resources can offer the same verb without importing each other's semantics, they do. Where they
must differ, the reason lives in one place. **Rejected, do not re-derive:** splitting them by
scope range (request scope is multi-writer), and splitting them by persistence (both persist).
The two conflict-retry drivers cannot be shared, only eliminated, because the stores model
deletion differently. *FIX-1157, wrapped Aug 28.*
4. **Capabilities, skills, tools, `ui` and thought-fabric are not removed.** Retracted by the
validation pass. *Original description.*
5. **The sequencer's public surface is not cut.** The review named two exceptions: `validate()`,
which is still on the surface, and `background()`, since renamed `sideChain` under its own
spec. *Original description; the rename settled separately.*
6. **Client data is private by default.** "Expose everything, with a hidden list" was rejected;
a scope names what crosses to the client. *Original description.*
7. **No backward-compat aliases.** A moved or renamed published export's old path is removed, not
aliased or re-exported. This is BP-034 held at scale: the owner made the call for clean SDK
("break, no backward-compat code") and it applied to every export the epic moved. Binds any
later epic that moves or renames a published export, vocabulary's renames included.
*FIX-2447, wrapped Nov 15.*
8. **The removed-root-exports release note is one summary line with the count**, not a name per
export. The owner's call. The adopter-goal check's upgrade journey, j5, confirms the line is
present on every run and checks the exact count only on the Version Packages PR
(`changeset-release/main`). So an epic that drops a root export from here on edits no changeset
until release; the count is reconciled there ([Rules](BUSINESS-RULES.md) → PR-2).
*FIX-2447 closure, FIX-2562.*
9. **The install docs keep pnpm's `--allow-build=better-sqlite3` flag until
[FIX-2737](https://linear.app/fixpoint-labs/issue/FIX-2737) lands**, moving store-sqlite to
`node:sqlite` so an install needs no native build. The owner's call. Binds the docs revamp,
which rewrites those pages: the flag goes when FIX-2737 merges, not before. *FIX-2447 wrap.*
10. **Removing exports from a package root is a `minor` bump before 1.0**, under BP-022. *FIX-2447.*

The source reports the original description names, a team synthesis and a validation synthesis
under `docs/internal/review*`, are not on `main` today. Where they disagreed, the validation
synthesis won; the list above is what it concluded.

## Open

### Does this project end at the public release, or stay open as the standing cleanup bucket?

**Plain terms.** This project was a three-week pass with a May 22 target. That pass is done bar
two package extractions. Since August it has become where "FSD says one thing, does another" fixes land: twelve
epics, 100 open issues, 68 under no epic. Nothing says when it is finished, so no epic can be
tested against a finish, and the bug count in [the outcome](SPEC.md) has no date to reach zero by.

**The trade-off.** Ending it at the public release gives it a finish line and forces one triage of
the 68: each either ships before release, moves to Public Launch's hard gates, or moves to a
post-release project. That costs a triage pass and some issues changing project. Keeping it as a
standing bucket costs nothing now, but it can never be called done, and it becomes a label.

**My recommendation.** End it at the public release. FIX-1127 made the case in August that the surface is
cheapest to make true before people build on it; the public release is the last point where that
holds, and after it each fix here is a breaking change for somebody outside. Set the Linear target to the release date once there is one; Public Launch
has none yet.

**What would change my mind.** If the release is a quarter or more away, tying this project to it
is a bucket with a date on it, and a narrower finish ("the 28 bugs") is the better line. Or if
cleanup is already tracked another way you would rather keep.

**What being wrong costs.** Low and reversible: a date and a label. The costly failure is the
other one, a project nobody can ever call done.
67 changes: 67 additions & 0 deletions spec/_projects/framework-simplification-and-cleanup/PLAN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Plan — Framework simplification & cleanup

[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · **Plan**

Sequencing, not building. What order the epics run in, what each hands the next, and what is
deliberately not next. Each epic's own plan owns its checks.

![The arc: twelve epic lanes from Aug 10 to Nov 15. Declared surface ran inside one day, Aug 12, and is done. Durable storage ran Aug 13 to Aug 28 and is done. Verified identity's direction merged Sep 22 and its bar runs to the now line with its one child not started. Keeping flows alive's direction merged Sep 29 and its bar runs to the now line with four of eight children done. One owner per fact, filed Oct 15, and durable agents, filed Oct 24, have no bar: both are in Backlog, though some of their children are done. The mechanism sweep ran Oct 30 to 31 and is done. Clean SDK's direction merged Nov 5 and it wrapped Nov 15. Vocabulary, feature kits and docs revamp each had their direction merged within a day or two of filing, Nov 7, Nov 9 and Nov 12, and run to the now line. Kit reads in the apps was filed Nov 11 and has no bar.](figures/arc.svg)

Two short closed bars in August, two long live ones since late September, then eight epics filed
in four weeks. Clean SDK is the first of those to close a long bar: ten days from direction to
wrap. Three more run behind it, each approved within two days of filing. Verified identity's bar
is still direction only, eight weeks on, and two Backlog epics have children landing with no
approved direction above them.

## What each epic consumes and releases

| Epic | Consumes | Releases |
|---|---|---|
| **declared surface** · FIX-1127 | A verification pass over this project's then 29 open issues, which closed 12 as shipped or superseded | **Released Aug 12:** a getting-started path that runs, flow options that are honoured or refused, declarations that stay on their block. Eight follow-ups filed |
| **durable storage** · FIX-1157 | Both storage primitives and their two conflict-retry drivers | **Released Aug 28:** increment and append on resources, one mutation contract, a delete that stays deleted; the write contract given one home in the docs. Decided once 2 and 3 |
| **verified identity** · FIX-1503 | Principal-owned org identity, already done outside any epic | A host-proof token mint, `/api/flows` verified by default, the two open reads closed, every HTTP consumer cut over, proved by the pentest Lab. **Not** login |
| **keeping flows alive** · FIX-1637 | The existing webhook, schedule and dispatch docs; Public Launch's queue-host session fence, pointed to and not moved | One guide, one glossary, one config matrix. **Not** a runtime change and **not** a new product noun |
| **clean SDK** · FIX-2447 | A review of what the Oct 16–31 window put on the public surface; every package root | **Released Nov 15:** curated package roots with no aliases, the adopter-goal check on installed tarballs passing on main `4d97cdc9a` with one expected-fail cell, `first-hour.quickstart`. Decided once 7 to 10, and PR-2. **Not** released: the quick start passing, 31 old `stores` lines, j5 in CI, all handed to [FIX-2739](https://linear.app/fixpoint-labs/issue/FIX-2739) |

## Coordination seams

- **Verified identity → keeping flows alive: one set of host-mount pages.** The config matrix
teaches how a host is mounted for webhooks, cron and event ingress; the identity cutover changes
how an HTTP caller proves who it is. Whichever lands second reads the other's pages, and
[PR-1](BUSINESS-RULES.md) holds both. If the guide ships first, the cutover's docs sweep must
include it.
- **Clean SDK → docs revamp: three leftovers in one issue.** [FIX-2739](https://linear.app/fixpoint-labs/issue/FIX-2739),
owned by FIX-2696, flips `first-hour.quickstart` to pass once the rewritten quick start uses the
`flows` list form, removes the 31 old `stores` lines, and folds j5 into the CI checks after
release. The revamp also inherits decided once 8 and 9: one summary line for removed exports,
and the install flag until FIX-2737.
- **Feature kits → kit reads in the apps.** FIX-2683 deletes the Teammates and Shift Manager read
models only once FIX-2618's views, reads by scope, notice ids and kits have shipped.
- **Keeping flows alive → Public Launch: a pointer, not a dependency.** The guide documents the
queue-host fence on delivering into an existing session honestly and links the fix in the hard
gates epic. It never waits on that fix and never absorbs it.

## Before the epics

The original pass ran in May as 19 issues in three tiers: cleanup, editorial, refactors. **16 done,
1 canceled, 2 open.** Both open ones are package extractions: the model layer, still here and
waiting on the model-layer complexity question, and voice, since moved to the Realtime Voice
project. The tier structure is not carried forward; later work runs as epics or as single issues.

**68 open issues sit under no epic**, 24 of them bugs, among them clean SDK's handoff and
follow-up, FIX-2739 and [FIX-2737](https://linear.app/fixpoint-labs/issue/FIX-2737). The two largest clusters are resource-store
correctness, where stores disagree or silently discard a write, and model strings. Neither has an
epic yet.

## What is deliberately not next

- **An epic for every open issue.** A single bug with a known fix takes the bug route on its own;
an epic is for a set sharing one objective.
- **The model-layer extraction** before the question of how much of that layer is essential is
answered.
- **Session delivery on a queue host.** It is Public Launch's hard gate; this project only
documents the fence.
- **A heartbeat or keep-alive product.** Keeping flows alive teaches what exists.
- **Writing the task-collection methods once**
([FIX-2462](https://linear.app/fixpoint-labs/issue/FIX-2462)), taken out of clean SDK into
Backlog until it is settled whether workforce keeps its own task-collection methods.
Loading
Loading