Skip to content

spec(project): Framework simplification & cleanup — standing project spec (never merge) - #2367

Draft
jhoffner wants to merge 7 commits into
mainfrom
project/framework-simplification-and-cleanup
Draft

jhoffner wants to merge 7 commits into
mainfrom
project/framework-simplification-and-cleanup

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

This PR is where FSD fixes the places its surface says one thing and does another, or offers two of something where a builder needs one, before its public release. It is never merged; it stays open as the project's live surface.

Winning when A builder can take every FSD doc, type and default at its word: nothing declared is silently dropped, no job makes them choose between two primitives, a reachable host is not open by default, and a common job such as keeping a flow alive has one published path. Nothing a builder can do today is cut to get there
The read Open issues labelled Bug in this project. 28 today; zero is done
Now 4 epics done · 5 in flight · 3 filed, not started. 100 open issues, 68 under no epic. No finish date
Kill line If a surface cut here keeps coming back within a release because builders needed it, the project is aimed at the wrong thing: what changes is layering, not the cut list

The territory renders in SPEC.md (Files tab, or the branch blob view at head b4a1518).

The fence is one test: does the change make an existing statement true, or remove a second of something? A change that adds a capability belongs to another project.

The arc renders in PLAN.md (same place).

Two short closed bars in August, two long live ones since late September, then eight epics filed in four weeks. Clean SDK closed its bar on Nov 15, ten days after its direction merged.

The epics, as of 2026-11-15 00:50 UTC (head b4a1518): FIX-1127 declared surface, FIX-1157 durable storage, FIX-2316 mechanism sweep and FIX-2447 clean SDK, done · FIX-1503 verified identity, in flight (Linear still reads In Spec Review, its one child in Backlog) · FIX-1637 keeping flows alive, in flight (4/8) · FIX-2600 vocabulary, in flight (4/5) · FIX-2618 feature kits, in flight (10/13) · FIX-2696 docs revamp, in flight (3/9, carries clean SDK's leftovers in FIX-2739) · FIX-2036, FIX-2171 and FIX-2683, filed, not started. The live table is in SPEC.md.

Clean SDK wrapped, and settled four things siblings should read rather than reopen (DECISIONS.md → decided once 7–10): no backward-compat aliases; removed root exports get one summary release line with the count, checked exactly only on the Version Packages PR (BUSINESS-RULES.md → PR-2), so an epic that drops a root export edits no changeset until release; the install docs keep pnpm's --allow-build=better-sqlite3 until FIX-2737; removing root exports is a minor bump before 1.0.

Open · one question for you (no gate)

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

Plain terms. This was a three-week pass with a May 22 target, now 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.

The trade-off. Ending at the public release gives a finish line and forces one triage of the 68 (ship before release, move to Public Launch's hard gates, or move to a post-release project). A standing bucket costs nothing now but can never be called done.

My recommendation. End it at the public release; the surface is cheapest to make true before people build on it. Set the Linear target once the release has a date.

What would change my mind. A release a quarter or more away, where a narrower line ("the 28 bugs") is better; or cleanup already tracked another way you prefer.

What being wrong costs. Low and reversible: a date and a label.

Reviewers · look here

  • Decided once 7–10 and PR-2. Clean SDK's wrap calls, raised here because the docs revamp, vocabulary and feature kits all touch published exports or the install pages.
  • The outcome and the read. Is "take every doc, type and default at its word" what this project should drive at, and is the open-bug count an honest read of it?
  • PR-1 in BUSINESS-RULES.md. FIX-1503's rule against teaching a caller-typed user id, raised to project altitude because FIX-1637 writes host-mount docs.

The set: SPEC.md · DECISIONS.md · BUSINESS-RULES.md · PLAN.md · absorbed/linear-content.md (the prior Linear content, verbatim), all under spec/_projects/framework-simplification-and-cleanup/ in this PR's Files tab · Linear project · never merged

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

This is a project-spec: the standing outcome, the cross-epic decisions, and the live state of
one Linear project, in four documents. It is not an implementation plan, not any one epic's
objective, and not a design.

In scope to challenge:

  • The outcome — is this what the project should be driving at, and would we know if we got there?
  • Whether the project overbuilds. Each epic can earn its place while the whole is too much.
    That question can only be asked here.
  • A decision in DECISIONS.md that binds several epics, or a rule in BUSINESS-RULES.md with no
    owner or two.
  • A missing epic the outcome implies, or one listed that does not serve it.

Out of scope — owned by the epic specs below it:

  • Any single epic's objective, issue division, or internals. Those are its epic PR.
  • The figures at the pixel level, and the status in the epics table, which is refreshed as
    the project moves and is never a review finding.

Feedback in the second list is routed to the epic it concerns, not folded in here.

🤖 Generated with Claude Code

https://claude.ai/code/session_011UNkLC9NknMcaqpK1h2mVK

…ar project content before the first build

Verbatim copy of the Linear project's content field (2201 characters,
updatedAt 2026-08-22T17:53:19.922Z), committed before the project-spec
mirror overwrites it, so every fold-or-drop call is reversible.

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

First build, dispatched by FIX-1637's EPIC_SETUP. Four documents plus the
territory and arc figures. Status derived from Linear: 2 epics done
(FIX-1127, FIX-1157), 1 in flight (FIX-1503), 1 not started (FIX-1637).

Absorbed from the prior Linear content: the original identity and the
retracted-cuts list (now Decisions -> decided once, and the no-epic-may
list). Left behind as stale: the 19-issue tier scope and its sequencing
notes (that pass is done bar two extractions; summarized in PLAN).

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

vercel Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-build-site Error Error Nov 15, 2026 12:58am UTC
3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Nov 15, 2026 12:58am UTC
flow-state-dev-kitchen-sink Ignored Ignored Nov 15, 2026 12:58am UTC
flow-state-dev-ui Ignored Ignored Preview Nov 15, 2026 12:58am UTC

Request Review

…FIX-1637 direction merged

FIX-1637 keeping flows alive moves to in flight (Spec Approved, 0/8,
spec merged Sep 29 19:51 UTC as 2b6d67e). Arc redrawn: FIX-1637 bar
starts at approval, FIX-1503 bar and the now line move to Sep 29 19:54.
Counts re-derived from Linear: 66 open, 55 under no epic, 26 bugs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GmvuVRtAQQvxJfj4fMVirA
@jhoffner jhoffner closed this Oct 6, 2026
…FIX-2447 filed

Status refresh only. The epics table, graph and arc now carry the four
epics filed since Sep 29 (FIX-2036, FIX-2171, FIX-2316, FIX-2447);
FIX-1637 moves to 4/8 and FIX-2316 shows as wrapped Oct 31. Counts
re-derived from Linear: 80 open, 35 under no epic, 20 open bugs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011UNkLC9NknMcaqpK1h2mVK
…FIX-2600 filed

Adds the vocabulary epic (FIX-2600) to the epics table, graph and arc.
Re-derives FIX-2447 (direction merged Nov 5, 2/20) and FIX-1637 (closure
spec approved) from Linear. Arc rescaled to 7px/day so the now line fits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011UNkLD7mJaky2QRikkQ8Z4
@jhoffner jhoffner reopened this Nov 7, 2026
jhoffner and others added 2 commits November 14, 2026 19:56
…K wraps

Wrap update: FIX-2447 to done (32/33 in Linear, FIX-2638 canceled into
FIX-2739); decided once 7-10 (no aliases, one summary line for removed
root exports, install flag until FIX-2737, minor bump pre-1.0); PR-2
owned by FIX-2447; the FIX-2739 handoff seam to the docs revamp.
Status refresh: rows for FIX-2618, FIX-2683, FIX-2696; FIX-2600 in
flight; arc redrawn to Nov 15.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011UNkLC9NknMcaqpK1h2mVK
…ecisions, rules, plan, arc

The rest of the wrap update (SPEC.md landed in the previous commit):
decided once 7-10, PR-2, the FIX-2739 and FIX-2618 -> FIX-2683 seams,
and the arc redrawn to Nov 15 with twelve lanes.

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

gitar-bot Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Code Review ✅ Approved 🟢 Low risk 1 closed / 1 findings

Adds project-spec, planning, and decision documentation without changing executable code or interfaces, so its direct behavior impact is limited.

Review completed with no unresolved findings.

✅ 1 closed
✅ Bug: DECISIONS.md still uses stale epic and issue counts that contradict SPEC/PLAN

📄 spec/_projects/framework-simplification-and-cleanup/DECISIONS.md:66 📄 spec/_projects/framework-simplification-and-cleanup/SPEC.md:16
The status refreshes updated SPEC.md and PLAN.md but missed DECISIONS.md. SPEC.md:17 says 93 open issues with 43 under no epic, SPEC.md:16 says 20 open bugs, and PLAN.md:43 says 43 unepic'd issues, 17 of them bugs. The open question in DECISIONS.md:52-56 still says "four epics, 58 open issues, 52 under no epic" and "one triage of the 52", and DECISIONS.md:66 offers "the 26 bugs" as the narrower finish line. The Cards section (DECISIONS.md:10-12) also still talks about "the two wrapped epics" and "the two live ones", but SPEC.md:40 now lists 3 done and 4 in flight out of 9 epics. This is the decision the author is being asked to make, so its trade-off is costed against figures the other documents contradict. Fix: refresh these figures from the same derivation used for SPEC.md, or point to the outcome table instead of repeating the numbers.

Verification

Rules No rules evaluated

Functional validation Not enabled

Set up

For more verification details, comment gitar display:verbose.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing compact verification results.

Comment with these commands to change the behavior for this request:

Auto-apply Compact
gitar auto-apply:on         
gitar display:verbose         

Important

Your trial ends in 4 days — upgrade now to keep code review, CI analysis, auto-apply, custom automations, and more.

Was this helpful? React with 👍 / 👎 | Gitar

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants